A.C.E. 3

home *** CD-ROM | disk | FTP | other *** search

/ A.C.E. 3 / ACE CD 3.iso / files / docs / candodoc.lha / CandoPart1.doc < prev next >

Wrap

Text File | 1994-11-27 | 155.1 KB | 3,773 lines

"The CanDo HowTo Book!" The CanDo Manual is computerized by SoftWare House RobbiSoft Dec.90'/Jan.91' What's in the CanDo HowTo Book?: Chapter 1 What Does CanDO Do? Page. CanDo Overwiew ................................................1-1 Whatzinabox? ..................................................1-1 CanDo System Requirements .....................................1-1 You CanDo a Backup ............................................1-2 CanDo on a Hard Disk or Floppy Disk ...........................1-2 A couple of questions you might have ..........................1-3 Chapter 2 You CanDo It. Starting Cando ................................................2-1 You CanDo an Application ......................................2-1 Lets Do It ....................................................2-1 First Project .................................................2-2 Second Project ................................................2-9 1 Chapter 3 Decks & Cards. Decks & Cards Overwiev ........................................3-1 Menus .........................................................3-1 Deck Menu .....................................................3-2 Card Menu .....................................................3-2 Mics. Menu ....................................................3-3 Status Panel ..................................................3-3 Edit Card .....................................................3-4 Card Editor ...................................................3-5 Chapter 4 Objects. Objects Overwiev ..............................................4-1 Buttons .......................................................4-5 Windows .......................................................4-14 Menus .........................................................4-20 Fields ........................................................4-25 Document ......................................................4-28 Timers ........................................................4-32 Sounds ........................................................4-34 Animation .....................................................4-37 Disk ..........................................................4-38 Routines ......................................................4-38 ARexx .........................................................4-39 Xtras .........................................................4-40 2 Chapter 5 Script Editor. Script Editor .................................................5-1 Editor Tools ..................................................5-4 Paint Editor Tool .............................................5-5 Text Editor Tool ..............................................5-8 Sound Editor Tool .............................................5-9 Picture Editor Tool ...........................................5-10 DOS Editor Tool ...............................................5-11 File Editor Tool ..............................................5-11 Coordinates Editor Tool .......................................5-11 Card Finder Editor Tool .......................................5-12 Routine Editor Tool ...........................................5-12 Field Editor Tool .............................................5-13 ARexx Editor Tool .............................................5-15 3 Chapter 6 Commands. Commands Overwiev .............................................6-1 Expressions ...................................................6-3 Functions .....................................................6-10 FlowControl Commands ..........................................6-18 CardMovement Commands .........................................6-23 Graphic Commands ..............................................6-24 Screen and Window Commands ....................................6-35 Brush Animation Commands ......................................6-38 Audio Scripting Commands ......................................6-42 Document Commands .............................................6-45 File I/O Commands .............................................6-53 Icon Commands .................................................6-55 ARexx Commands ................................................6-58 Object Commands ...............................................6-60 Buffer Commands ...............................................6-62 Mics. Commands ................................................6-66 4 Chapter 7 Appendices. Commands Index ................................................7-1 LoadFlags Appendix ............................................7-7 Advanced Features .............................................7-8 Error Messages - Syntax Errors ................................7-10 Error Messages - Run Time Errors ..............................7-11 Error Messages - File Errors ..................................7-13 5 Chapter 1 What Does CanDo Do? CanDo is a revolutionary, Amiga specific, interactive software authoring system. Its unique purpose is to let you create real Amiga software without any programming experience. CanDo is extremely friendly to you and your Amiga. Its elegant design lets you take advantage of the Amiga's sophisticated operating system without any technical knowledge. CanDo makes it easy to use the things that other programs generate - pictures. sounds, animations, and text files. In a minimal amount of time, you can make programs that are specially suited to your needs. Equipped with CanDo, a paint program, a sound digitizer, and a little bit of imagination, you can produce standalone applications that rival commercial quality software. These applications may be given to friends or sold for profit without the need for licenses or fees. Although CanDo is especially easy to use, it is extremely powerful and versatile. Its uses range from building simple slide shows and interactive presentations to animated multimedia productions, quality educational software, and even sophisticated control applicatons that communicate with external video and audio equipment. CanDo lets you build small programs and add features as you need them. Since Cando opens the world of software development to all Amiga users, is has the potential of making an endless number of applications available to every Amiga owner. We are very excited about this becoming a reality and hope to facilitate it with future enhancements and support. Whatzindabox? Along with this Manual, the package should contain Two Disks: CanDo and CanDoExtras. Also included in the box is a Registration Card that you should take the time to fill out and return to us. This will enable us to inform you of CanDo revisions and will help our technical support staff to help you. Please take a look at the ReadMe files on each of the CanDo Disks. They contain last minute information that was not available when this Manual was printed. They may be viewed by doouble clicking their icons. CanDo System Requirements CanDo will work on any Amiga computer that has at least on (1) megabyte of memory. If you don't have a hard drive, it is recommended that you have two 3 1/2" floppy drives. Since CanDo makes it easy to work with sizable data like pictures and sounds, a hard drive and expanded memory will dramatically increase your effciency and productivity. Be sure your Amiga is running WorkBench version 1.2 or greater. This manual assumes you are familiar with the operation of your computer as wxplanied in the manual that came with your Amiga. You should know how to use the mouse, start applications from WorkBench, and do simple WorkBench operatons. 1-1 You CanDo a Backup Please, before you use CanDo, make copies of all the original disks. Work with these copies and keep the originales in a safe place. For your convenience CanDo is not copy protected so spread the word not the disk. TO MAKE COPIES OF THE CANDO DISKS: 1. Write-protect both CanDo disks by flipping up the write protect tab on the disks. This will protect them from accidental erasure. 2. Place the CanDo disk into drive DF0: and select the disk icon so that it is highlighted. 3. Select Duplicate from the WorkBench menu. Select Continue when asked to insert CanDo. 4. Insert a blank disk into drive DF0: when asked for the disk. 5. Exchnage disks when requested and select Continue until the copy is complete. 6. Once you have a copy, rename it by highlighting the disk icon and selecting Rename from the WorkBench menu. Remove the "Copy of" text that was appended to CanDo. Be sure to delete any spaces that precede the name. 7. Repeat the procedure for the CanDoExtras disk. CanDo on a Hard Disk or a Floppy Disk CANDO ON A HARD DISK OR A FLOPPY DISK CanDo is easy to install on your hard disk. You'll need at least one (1) megabyte free on your hard disk before copying CanDo and all the support files. For floppy disk owners, CanDo will run directly from the working copy you maed. You must start your Amiga with this CanDo disk and run CanDo from the icon. You will likely choose to install CanDo on your own WorkBench startup disk. This is done by using the CanDoInstall program found on the CanDoExtras disk. TO INSTALL CANDO ON YOUR WORKBENCH DISK OR YOUR HARD DISK: 1. Start your computer normaly andthen insert the CanDoExtras disk into drive. 2. Open the CandoExtras disk by double clicking its icon on WorkBench. Open the Utilities drawer. 3. Now the Installer program may be started by double clicking on its icon. 4. This program will guide you through the installation process for both floppy drives and hard drives. 5. Once the installation is complete, you may remove the CanDoExtras disk and close its window. 6. CanDo may mow be started from your floppy or hard disk by double clicking its icon. 1-2 A couple of questions you might have... WHY DO I NEED TO "INSTALL" CANDO? When CanDo is started, is looks in an Amiga system directory called LIBS: and another called L: for support files. These particular directories that the Amiga uses to keep special files. The CanDoInstall program copies these files for you. WHAT AM I CREATING WHEN I USE CANDO? The applications you create with CanDo are called Decks. This is because they comprised of Cards. In CanDo you work with Cards one at a time and they may have completely different environments and characteristics. When you save a Deck from CanDo, it is like an executable program that you may start by double clicking its icon on the WorkBench screen. These Decks are actually small files that use a "Library" that is installed on your system. All CanDo Decks and CanDo itself efficiently share the use of this library. This arrangement enables you to run many Decks at the same time and use the Amiga's memory and its resources to the full extent of its capabilites. Remember, the CanDo library is not a distributable protion of CanDo. HOW DO I MAKE A DISTRIBUTABLE CANDO APPLICATION? When you are ready to make an executable version of your program, you can do so easily with the Binder. This utility can create a distritable version of your project in either of two ways: 1. INDEPENDENT PROJECT: A form of your Deck whick will run on any Amiga, regardless of whether or not CanDo is also available on the Amiga. Programs produced in this way can be sold or distributed without a license or fees of any kind. These programs have the primary part of the CanDo support software built into them. 2. DEPENDENT PROJECT: A form in which the project will only run if you or your friends, or potential customers, have CanDo already. This type of bound project is significantly smaller in size than an Independent Project (it shares the same library of functions that CanDo uses), and is the perfect way to make a program which you intend to give or sell only to people who already own CanDo. 1-3 To "Bind" a Deck, select the Deck's icon the you would like to make standalone and then, while holding down the shift key, double click on the Binder icon. It will guide you through the binding process and create a standalone application. Remember the icon for your new application will not be visible in a WorkBnech window until it is re-opened. The standalone deck may now be distributed along with any graphics or sound files that it uses. Don't forget that these resource files must be found in the directories that were specified when the Deck was created. CAN I MAKE ROOM ON MY CANDO DISK IF I DON'T NEED ALL THE FEATURES? CanDo is very modular in design. If you don't need some of its features, you may remove them from your disk. If you don't use ARexx objects you may open the Objects drawer and discard it. Similarly, you may discard items in the EditorTools,Xtras, and HelpFiles drawers. Make sure you have a backup of these files in case you need these features in the future. The modular design of CanDo also enables you to add features in the future when they become available. HOW DO I GET HELP? If you have a problem that this manual does not address, please call our Support Staff at: +1 214 340 4992 or if you have a modem, you can call our Product Support BBS at: +1 214 357 8511 (300/1200/2400 Baud) 1-4 Chapter 2 You CanDo It. There are two methods of starting CanDo. FIRST: CanDo has a Workbench Icon. Double-clicking on this Icon automatically launches the program. SECOND: CanDo may be launched from a CLI or Shell by typing CanDo and then pressing RETURN. CanDo will begin to load. THE CANDO REPORTER, a small message window, will appear and inform you that the files that makeup CanDo and its user interface are loading. The last message you will see is "All done, finishing up." Now, at the bottom of the display, you will see CanDo's MAIN CONTROL PANEL and behind the panel is your default window. You CanDo an Application. The first sorfware project that you're going to create is a very simple one. When executed, this Program will open a Window, (or Card as we will now call them). All CanDo applications consist of Cards and Decks. Cards are the basis building blocks of any CanDo project. A Card contains a single Window and all its Objects and Attributes. A Deck consists of several Cards. Moing between Cards and Decks is a fundamental part og CanDo project design. We will begin working on the first Card of this three Card project. It will have a full screen IFF Image displayed. On this Image, we are going to place two Buttons (or Gadgets in Amiga-ese), one with the words "Next Critter" written on it, and the other with the word "Quit". When the Button marked NEXT CRITTER is clicked, a second IFF Image will be shown. Clicking it again shows a thrid Image. Each Image is its own Card, with Buttons identical to the ones on the other Cards that you have created. When any of the Buttons marked QUIT are clicked, the program will stop and the user will be returned to the CLI or Workbench. Lets Do It. On the CanDo MAIN CONTROL PANEL there are three boxes: Status, Cards, and Objects. There are two Buttons in the Status box: Design and Browse. Selecting DESIGN allows you to create your projects. You can select BROWSE to test or run your creations at any time, without exiting CanDo. Ready to start? 2-1 1. Click on the DESIGN Button to begin working on your project. 2. Click on the WINDOW Button (Pic.#1/Fig.#1) in the OBJECTS protion of the MAIN CONTROL PANEL. This is the first step in the creation of a background image for your first Card. You'll be shown the WINDOW EDITOR. This is how you'll describe your window. You can type your Window's name in the Field under "Window Title" but for this example, we want to clear out the default name. 3. Click in the Field then press the RIGHT AMIGA KEY + X which will clear the Field. This will produce a blank Title Bar above your Window, giving it a cleaner look. 4. Now click on the DIMENSION Button. The DIMENSION REQUESTER appears. (Pic.#1/Fig.#2) 5. Click on the Button to the right of "Picture". This brings up CanDo's FILE REQUESTER. Use the requester to locate the file RABBIT.PIC that was incluced on your CanDoExtras disk. Refer to chapter 4-4 of the manual for information on how it operates. 6. Choose the RABBIT.PIC file. The Path Field now showes the correct directory path and the File Field shoes "Rabbit.pic." 7. Now click the OK Button. This will return you to the DIMENSION REQUESTER. The Button nest to "Picture" now shoes, the highlighted Name RABBIT.PIC, the File you chose. When your Window odes open it will have the proper dimensions and resolution for the picture file you have just chosen, with the picture as it's background. 2-2 8. Again click the OK Button. This returns you to the WINDOW EDITOR. On the right, you'll see several Buttons. You've already used the first one "Dimension". For this application, you'll also use the bottom one, "Options." 9. Click on the OPTIONS Button. This will bring up the OPTIONS REQUESTER which has several choices. For this example, you will need to change only one of the default settings. 10. Click on the first Button, THE WINDOW HAS VISIBLE BORDERS. The Button will change to THE WINDOW'S BORDERS ARE INVISIBLE. 11. Now click on the OK Button. This will return you to the WINDOW EDITOR. (Pic.#1/Fig.#3) 12. Now click on OBJECTS. Thi brings up the OBJECTS REQUESTER. Click on the CLOSEBUTTON icon to deselect it, we won't need one. Click OK. 13. Click on the WINDOW EDITOR's OK Button. There's your Rabbit. You've created your Window and you are back at the CanDo MAIN CONTROL PANEL. To see the whole picture... 14. Click on the UP/DOWN ARROW Button on the right side of the panel. The panel will drop out of the way. 2-3 15. Click the UP/DOWN ARROW Button again and the panel returns the to its working position. You're now ready to add a title to this picture. To do this you need to write a Script. 16. Click on the EDIT CARDS Button (Pic.#1/Fig.#4) in the Cards portion of the MAIN CONTROL PANEL. This will bring up the CARD SYSTEM. Here you will see a card Requester with one file name in it "Card#1". This is the Card you've been working on. Since it is already selected... 17. Click on the EDIT Button. This will bring up the CARD EDITOR. here you see three Button that allow you to attach Scripts to your Card. But what is a Script anyway? A script is a Command (or, more often, a series of them) to be executed under certain conditions in a CanDo project. A Script is often attached to an event in your application. In other words, events like clicking a Button, activating (clicking on) a Window, or goind from one Card to another can cause a Script of Commands to be executed. Script Commands can beused to play a sound or sound sequence, run animations, move from one Card in a Deck to another Card, add text to a Window and many mor complex tasks. While this example project uses scripts in their basic, most straight forward form, you may wish to take a moment to look at the complete list of Scripting Commands, together with descriptions, syntax, and examples, that appear in the Commands Section of this manual. This side trip will give you an idea of the power and simplicity of CanDo's Scripting Languarge. 2-4 18. Now back at The CARD EDITOR, you will need to choose one of the three Buttons to add tie title to your picture. Your chices are: at the Card's StartUp. AfterStartUp, or when Leaving the Card. You want the title to appear in your Window immediately after the Rabbit graphic is displayed. Click the AFTERSTARTUP Button. 19. In the SCRIPT EDITOR (Pic.#2/Fig.#5), type the following lines verbatim. SETPAN 2 PRINTTEXT "The Friends of Elly Mae",70,45 The Setpen Command sets the color of the text to be written from the Window's palette. The PrntText Command simply prints the text within the quotes at the coordinates specified ( 70 , 45 ). This means 70 pixels over and 45 pixels down. 20. Click the OK Button to ad this Script to your project. 21. At the CARD EDITOR, click OK. 22. Now click EXIT to leave the CARD EDITING SYSTEM. You're back at the MAIN CONTROL PANEL. You may want to go into Browse mode to check your creation so far. 23. Click BROWSE in the STATUS PANEL. In the Cards portion of the MAIN CONTROL PANEL you see an Arrow (Pic.#1/Fig.#6) Button pointing to the right, that's the NextCard Button. When the NextCard Button is clicked, the next Card in your Deck in rendered (or "started-up") on Screen one after another. When you reach the last Card in your Deck and click NextCard again, CanDo loops back to the first Card in the Deck. Since we have only one Card so far in this example, clicking the NextCard Button will result in looping back to the same Card. 2-5 24. Now click the NEXTCARD Button. Your Card, picture, title and all will be freshly rendered on your Screen. Not bad!. Now, we want to make this good lokking window do something else, so let's Add some Buttons. 25. First, click on the ADD Button in the OBJECT PANEL. 26. Then, click on the BUTTONS Button (Pic.#1/Fig#7) in the same panel. The BUTTON OBJECT SYSTEM REQUESTER will appear. This Requester asks you to locate the Origin Point of your new Button. 27. Click the OK Button. The EDIT BUTTON REQUESTER will be lowered revealing your full Screen. Move your Mouse to position the Pointer on Screen where you want your Button. For this execise move the Pointer to above the "T" in the word "The". 28. Now click and release the LEFT MOUSE Button to set the Origin Point. Move your Mouse, notice that it now controls the shape and size of a rectangle. Move the Mouse in any directon you choose, adjusting the rectangle until you are satisfied with its size and shape. If you don't like the Button for some reason, click the ESC Key and start the process over. 29. If the location and shape are to your liking, click the LEFT MOUSE Button. The BUTTON EDITOR REQUESTER will be displayed and the location (origin) coordinates of the Button you've just created, in horizontal and vertical format, will have been entered for you automatically. You will also see the Button shape you have created positioned on the Screen. You may edit these by clicking in the field and typing new coordinates. Edit "Horiz" to be 50 and "Vet" to be 25. There are three types of Buttons in CanDo: Area, Text, Image. The Button we're making will be a Text Button. 2-6 30. Press the BOX next to "Text". This brings up the FONT/TEXT REQUESTER. Here you will select your Font. The default setting of Topaz 8 Plain will work well here. Notice, there are several style options available. This time choose SHADOWED. You'll also see three COLOR SELECTORS. Click the left one, it governs the color of the text on your Button. Across the bottom of the Screen you will see a Color Palette. Click on a bright, light color. Your choice will be displayed in the Selector you clicked on. You can also choose colors using the Arrows on the Selector. You may change the second Color Selector to suite your tastes. Try it. 31. Now, click in the "Text" Field and press the RIGHT AMIGA Key and X to clear the Field. Now type... QUIT This text will become part of the Button. 32. Click the OK Button. This will return you to the BUTTON EDITOR REQUESTER. To enable the "Quit" Button to actually end a project we must attach a Script to it. There are four Button Events which can trigger a Script. This time you want the Script executed when the Mouse Button is let up after being pressed. This is called a Release script. 33. Click on RELEASE in the Scripts portion of the Requester. A SCRIPT EDITOR REQUESTER will appear. Type: QUIT 34. Click on the OK Button. 35. At the EDIT BUTTON REQUESTER, click on the OK Button. Now you're back at the MAIN CONTROL PANEL. The procedure for making the second Button is exactly the same as the first except that this Button's text and positon will be different. 36. Click no ADD and then on the Button in the MAIN CONTROL PANEL. Place this Button's Origin to the right of the "Quit Button" you just created and draw another small rectangle. You may adjust its coordinates to a horizontal of 175 and a vertical 25. This time, the text for the button will be "Next Critter" and its Release Script will be: NEXTCARD When you have your new button finished you should click OK at all Requesters until you're back at CanDo's MAIN CONTROL PANEL. Now when you click "Next Critter" the project will go to its Next Card, which will also contain a Picture and some Buttons. What next Card you say? You can make on in less then thirty seconds. 2-7 37. Click on the Edit Cards Button in the Cards portion in the main panel. This brings the CARD SYSTEM back up. Click on the DUPLICATE Button on the right of the Requester. A second Card will added to your project. This Card is a duplicate of your first Card. Since your first window was a Picture Window, the window in your second Card will be a Picture Window as well, complete with same graphics. The new window also has the same Window Options and Window Objects as the first window. The Buttons and scirpts are carried over to the new Card. 38. This window will require changes to the script, so, here at the CARD EDITOR, click on AFTERSTARTUP. When the SCRIPT EDITOR comes up, select the menu option CLEAR under the Scripts menu. Click YES to verify that you really want to du this. Then click OK to leave the SCRIPT EDITOR. Click Ok at the CARD EDITOR. Exit the Card Editing system. Your are now working on a new Card. And since we don't really want two pictures of the same rabbit, let's change the graphic to a different critter. 39. Click the WINDOWS Button on the MAIN CONTROL PANEL. In the WINDOW EDITOR, click on DIMENSIONS and then select PICTURE Button again to get the FILE REQUESTER. When it comes up, select the graphic file PORCUPINE.PIC. Click OK. Since the options of first window are carried over to this one, and we want to use them as they are, you cdan now click OK. Your second Card is now finished and operational. 40. The third and final Card will be by far the easiest to create. We are going to clone the second Card, complete with graphic, buttons, and scripts. Then, we'll simply substitute a new critter pic. 41. Repeat step 37 and there's no need to edit the AfterStartUp Script. 42. Repeat step 38 and this time use the MINK.PIC file. Return to the MAIN CONTROL PANEL. If you want, you can change the border style or text color of any button by clicking EDIT and then on the actual button you would like to edit. 43. If you're not at the MAIN CONTROL PANEL, return to it for your final step in this project. Under the "Deck Menu", select SAVE. You will be prompted to give a filename and pathname. Now click OK. And that's it! You've just created a working program. Congratulations. 2-8 Second Project Your second Project will be very different from the first. It will be an extremely useful and flexble Application, and in some ways, easier to create the your first one was. We call this Application a "PowerPanel" and it puts almost any Amiga Command or Application just a click of the Mouse away. You create it using CanDo's DOS Command. This Command allows you to run any Program as though it was a CLI Command. Because all Programs cannot be run through CLI, you should always consult the Program's Documentation before using it with CanDo's DOS Command. The PowerPanel. A PowerPanel is (or at least can be) a Window that opens on the Worbench Screen with several Buttons on it. For example, there could be a Button that says "Paint" on it. When the Button is clicked, the PowerPanel could start your favorite paint program. These PowerPanel Buttons can set up entire environments: change directories, make assignments... do almost anything. This PowerPanel example will be designed to perform functins accessible to all Amiga / CanDo users: * Run CanDo * Run Phone Index ( a CanDo application ) * Open a new CLI * Run the Workbench Calculator Utility. * Play some Sampled Sounds ( just for grins ) They're a breeze to create and run, so lets get started. 1. Click the DESIGN Button. 2. Click on the WINDOWS Button in OBJECTS. The WINDOW EDITOR REQUESTER will appear. 3. Clear the "Window Title Field" and replace the title with... POWERPANEL 4. Click on the DIMENSION Button. (Pic.#1/Fig.#2) 5. The DIMENSION REQUESTER, appears. In the "Position and Size" portion set the Window's X coordinate to 50 and the Y coordinate to 15 2-9 6. Set the Window's Width to 177 and Hight to 78. 7. You'll use four colors ( the Workbench colors ), so click on 4 under "# of Colors". 8. Click OK to return to the WINDOW EDITOR REQUESTER. 9. Click on the OBJECTS Button to open the OBJECT REQUESTER.(Pic.#1/Fig.#3) Here you see graphic representations of these familiar Amiga Window objects: Close Button, Depth Buttons, Drag Bar and Resizing Button. When added to CanDo Projects, all four Objects perform their standard functions. For example: a Window's Close Button will execute a Script when clicked which could quit the program, go to the next card, or perform any CanDo Command. For this Project select the CLOSE BUTTON, DEPTH BUTTON, and the DRAG BAR. When selected, their Buttons will be highlighted. Click OK to record these choices. 10. At the WINDOW EDIT REQUESTER. Click OK You are back at the MAIN CONTROL PANEL and a smaller Window has been opened on your Workbench Screen. This is your PowerPanel Window an you're ready to create your PowerButtons. First, we'll Add the Button that starts CanDo. It will be a Text Button and will be created in the same manner as the Quit Button in the First Tutorial Project. Only the placement of the Button on the PowerPanel Screen and the Text on the Button will be different. 11. Click ADD and the BUTTON Button under Objects. 12. At the Add New Button Requester click OK. 13. Move the Pointer to a position in the upper left corner of your PowerPanel Window. Click the LEFT MOUSE Button to set the Origin Point. Size the Button rectangle as before and click the LEFT MOUSE Button. 14. At the EDIT BUTTON REQUESTER in the Origin section adjust the Button's Origin Point by changing the Horizontal and Vertical coordinates to 13 and 14. The exact size you made this Button is unimportant because it will automatically adjust to the size of the Text that we put in it. 2-10 15. Now click on OUTLINE in the Border section. 16. At the BORDER SELECTOR click on the EMBOSSED Button. Now choose the Border Colors you want using the COLOR SELECTORE and click OK. 17. At the BUTTON EDIT REQUESTER click on the BOX next to "Text" under "Style". The TEXT BUTTON DEFINITION REQUESTER will appear. In this Requester you will set these parameters: Font: TOPAZ Font Size: 8 Font Style: PLAIN Text Color: ( Your Choice ) Text: CanDo With these settings click OK. 18. At the BUTTON EDITOR REQUESTER click the RELEASE Button under "Scripts". 19. At the SCRIPT EDITOR, the far right hand slider controls a List of Editor Tool Icons. Locate and the Select the DOS Editor Tool. (Pic.#1/Fig.#8) 20. At the CANDO FILE REQUESTER use the File List on the right to find, then Select the CANDO Program File. Click OK. 21. At the SCRIPT EDITOR you will see that the proper DOS Scripting Command has been automatically typed into the Editor. Click on OK. 22. At the EDIT BUTTON REQUESTER click OK. The MAIN CONTROL PANEL, your PowerPanel Window and it's first Button will appear. 2-11 The remainder of the Buttons you will define for this Project are Text Buttons alson. Retrace steps 11 through 22 which you used to create your first PowerButton but use these Button Definitions below. Other possible differences can be variations in Font choice, Text Color and Border Style. Use the DOS EDITOR TOOL to locate the program each button will start. Following is a description of each Button you need to define: Phone Index Button Button Co-ordinates: 72, 14 Border Style: EMBOSSED Font: TOPAZ Font Size: 8 Font Style: PLAIN Text Color: ( Your Choice ) Text: PHONE INDEX Program: CanDoExtrax:Utilities/PhoneIndex Calculator Button Button Co-ordinates: 13, 32 Button Style: EMBOSSED Font: TOPAZ Font Size: 8 Font Style: PLAIN Text Color: ( Your Choice ) Text: CALCULATOR Program: Sys:Utilities/Calculator New CLI Button Button Co-ordinates: 112, 32 Button Style: EMBOSSED Font: TOPAZ Font Size: 8 Font Style: PLAIN Text Color: ( Your Choice ) Text: NEWCLI Program: C:NewCLI 2-12 23. Return to the MAIN CONTROL PANEL. Now, let's add some text to the Window to explain that the Buttons at the bottom of the panel that we are about to add are for playing sounds. Click on the EDIT CARDS Button in the CARDS BOX. The CARD SYSTEM REQUESTER will appear. Press the EDIT Button to edit the only card listed, "Card#1" The CARD EDITOR REQUESTER will appear. Press the AFTERSTARTUP Button to add the Script that will be performed after the card's window has been opened and all the Buttons have been attached. 24. You want to print the text "Sound Samples" just below the Buttons you've already made. Type in the followind Script. SETPEN 1 PRINTTEXT "Sound Samples",35,48 PRINTTEXT 25. Press OK to save the Script. This will return you to the CARD EDITOR REQUESTER. 26. Press OK again to return to the CARD SYSTEM REQUESTER. 27. Now press EXIT to return to the MAIN CONTROL PANEL. 28. Click on BROWSE, and then click the NEXTCARD Button in the Cards panel. You'll see the text you just created appear in your Window. 29. Now click the DESIGN Button. You're going to add a few simple unmarked rectangular Buttons. Each one, when clicked, wil play a different sampled sound. 30. Click on EDIT and then on the BUTTONS Button in the Objects panel. 31. At the BUTTON EDITING SYSTEM, click ADD. When prompted, place the Origin of the first of these sound buttons in the lower left corner of your Window. This Button is going to be an "Area Button". When the EDIT BUTTON REQUESTER comes up, rename this Button "Sound1". Then, adjust the Button's co-ordinates to 13, 62. 32. Click on AREA and the AREA BUTTON REQUESTER will appear. Adjust the Button size to 25,10, using the Width and Height Fields in the Requester. All of our "Sound Buttons" will be this size. 33. Click OK to return to the EDIT BUTTON REQUESTER. The Border and High light styles may be experimented with, but the defaults will work well for your purpose. Now, you'll want to add a Release Script, so click RELEASE. 2-13 34. At the SCRIPT EDITOR, click the SOUND EDITOR TOOL (Pic.#1/Fig.#9) on the right. 35. Select SET THE FILENAME from the PLAY A SOUND REQUESTER. This will bring up CanDo's FILE REQUESTER. Find the DOGBARK.SND file, select it and then click OK. 36. Click OK at the PLAY A SOUND REQUESTER. The PlaySound Command will have typed into your script. Click OK to save the script. 37. At the EDIT BUTTON REQUESTER. Click OK. You are now back at the MAIN CONTROL PANEL. There will be three more "sound buttons" like this one, except with different co-ordinates and different sounds attached. REPEAT STEPS 29 THROUGH 36 USING THE BUTTON DEFINITIONS BELOW: SOUND 2 Button Name: Sound2 Co-ordinates: 55, 62 Area Button Size: 25, 10 Sound file: ( Your Choice ) SOUND 3 Button Name: Sound3 Co-ordinates: 97, 62 Area Button Size: 25, 10 Sound file: ( Your Choice ) SOUND 4 Button Name: Sound4 Co-ordinates: 139, 62 Area Button Size: 25, 10 Sound file: ( Your Choice ) Save your Deck now. Under the Decks Menu Select "Save". Use CanDo's File Requester to set the Path and File Name for your Deck. Click OK and you're done. 2-14 Chapter 3 Decks & Cards A CanDo project is comprised of a Deck of Cards. CanDo Cards are somewhat like Flash Cards in that only one is shown at a time. However, unlike Flash Cards that only present information, CanDo Cards can both present and receive information. Furthermore, you can make things "happen" on a CanDo Card. You do this by making Objects. The Window Object allows you to specify the overall appearance of your Card. Buttons and Menus, for example, allow the user of your project to tell it to do something. Other Objects allow you to easily receive information or otherwise control what is happening. By adding Objects to a Card, you design what it looks like and what it does. The Card is simply a container for the Objects you give it. Some applications only need a single Card, while others need many Cards to change the interface, appearance or activity. By simply changing Cards, you can cause dramatic or subtle differences in what is happening. When you have designed a Deck, you can save it to disk. This allows you to later load that Deck back into CanDo for futher editing. The Deck can be run separately by double clicking its icon from Workbench, or from a CLI using the CanDoRunner program. When you are ready to make an executable version of your program you can do so easily with the CanDo's Binder. It will create a new file that is a runnable program. However, the program created by the Binder can not be re-edited by CanDo. Make sure that you keep the original Deck saved by CanDo for later editing. This Chapter tells you how to work with Decks and Cards. Chapter 4 describes the Objects you can add to a Card. Chapters 5 and 6 describe how to write the Scripts that make your application come to life. Menus When CanDo's Main Control Panel is the active window, you can access CanDo's Menus. They are not accessible when hour application's Window is active. By clicking on any portion of the Main Control Panel, not necessarily on a Button, you activate the window. This gives you access to CanDo's Menus when you press the right mouse Button. CanDo's Menus are: Deck, Card, Objects, and Misc. The Objects Menu is described in Chapter 4. 3-1 Deck Menu The Deck Menu has five items: New, Open, Save, About, and Quit. NEW New deletes all existing Cards and starts you up in the default configuration. (see the Advanced Topics Appendix for changing the default Deck.) OPEN Open replaces the current Deck with on loaded from a file. CanDo's File Requester allows you to locate the file. The file must be a Deck created with CanDo. You cannot load a Deck that has been made into a stand-alone program using CanDo's Binder. SAVE Save writes the current Deck to a file specified with CanDo's File Requester. A saved Deck can be loaded into CanDo using Open. It can also be run separately by double clicking its Icon, or bound into a stand-alone program using CanDo's Binder. ABOUT About simply displays a little information about INOVAtronics and CanDo. QUIT Quit allows you to leave CanDo. A Requester will warn you if you have modified the current Deck. Card Menu The Card Menu has five items: Goto, First, Last, Previous, and Next. GOTO Goto... allows you to go to a specifiec Card. A requester will show all the Card Names. Click on one of the names to highlight it. Clicking on the Goto Button or double clicking one of the entries will cause you to change Cards. When you want to stay on a Card, select the Exit Button. FIRST First causes CanDo to go to the First Card in the Deck. LAST Last causes CanDo to go the Last Card in the Deck. PREVIOUS Previous causes CanDo to move back one Card. If you are on the First Card, this will put you on the Last Card. NEXT Next causes CanDo to move forward on Card. If you are on the Last Card, this will put you on the First Card. 3-2 Misc. Menu The Misc. Menu has two items: SuperBrowse and System Info. SUPERBROWSE SuperBrowse temporarily removes the CanDo interface to your application. The MAIN CONTROL PANEL will disappear, and your application will be able to interact a little faster. This mode allows you to see exactly how your application will run as a separate program. When you enter SuperBrowse Mode, CanDo will open a small Window on your Workbench Screen. When you double-click on the Window, CanDo's MAIN CONTROL PANEL will reappear and you will no longer be in SuperBrowse Mode. SYSTEM INFO System Info will display a requester displaying Available Memory, CanDo version information, and other useful statistics. Status Panel The Status Portion of the MAIN CONTROL PANEL (Pic.#2/Fig.#10) contains the Browse and Design Buttons. BROWSE By selecting BROWSE, you can test your application. Because CanDo is monitoring your activity, your project will not be as responsive as when it is running in SuperBrowse Mode or as a separate application. DESIGN When DESIGN is selected, you can construct your application. Selecting any Button on the MAIN CONTROL PANEL, other than Browse, will automatically select Design. The FIRST, LAST, PREVIOUS, NEXT, and GOTO Buttons work the same as their Menu counterparts. 3-3 Edit Card Selecting the EDIT Card Button brings up the CARD LIST REQUESTER (Pic.#3/Fig.#11). From this Requester you can Add, Edit, Delete, Duplicate and Reorder Cards. This list on the left side of the CARD LIST REQUESTER contains the names of all the Cards in the Deck. You can highlight a Card Name by clicking on it in the list. The Buttons on the right side of the Requester will work with the highlighted entry. ADD The Add Button allows you to Add a new Card to the Deck. The New Card will not contain any Objects. When you click this Button, the CARD EDITOR REQUESTER will be displayed. This Requester is described later in the Chapter. EDIT The Edit Button allows you to edit the currently highlighted Card. If you double-click a CARD NAME, it will also edit the Card. In either case, CanDo will go to the selected Card and display its CARD EDITOR REQUESTER. DELETE The Delete Button deletes the highlighted Card. A Requester will ask you if you really want to delete it. Be certain that you want to delete it. The Card and all of its Objects are disposed of completely. DUPLICATE The Duplicate Button makes a copy of the selected Card and Objects. THE CARD EDITOR REQUESTER is then displayed for this Card. This allows you to begin a new Card with a copy of the existing Objects. The list shows the Cards in the current order. The two large ARROW Buttons allow you to reorder the Cards. By using these Buttons, you can move the highlighted Card up and down through the list. 3-4 Card Editor The CARD EDITOR REQUESTER (Pic.#3/Fig.#12) has a Field for the Card Name and three Buttons for Scripts. You can change the Card Name by simply changing the name in the field. The Card has three Scripts associated with it: Startup, AfterStartup, and Leaving. STARTUP The StartUp Script is performed before your Card's window opens and before any other Objects on your Card are created. This is a good place from which to initialize variables, load files, etc. Because the window has not yet been opened, this Script cannot perform any sort of grphics commands. AFTERSTARTUP In this Script, which is performed after your Card's window opens and before (like Buttons) have been made, you may want to draw into your Card's window, activate a particular text field, start a BrushAnimation or sound playing, or perform other last-second steps before the user of your application begins to interact with it. LEAVING The Leaving Script is performed anytime you switch Cards. This Script runs after your Card's Objects have been removed from the window. This is the proper place to save any files that were changed on the Card that is ending, before moving on to another Card or quitting entirely. NOTE: You cannot put any Card Movement Commands in the Leaving Script. 3-5 Chapter 4 Objects Lets start with some CanDo basics. Applicatons are comprised of a Deck of Cards. You can have as many Cards in a Deck as you wish. Each Card in the Deck has a Window. Like flash-cards, CanDo Cards are shown one at the time. It's up to you how each Card looks. They can look similar to each other or they can look completely diferent. CanDo gives you a lot of freedom using the Amiga graphics and sounds. CanDo Objects, such as Buttons and Menus, are added to a Card allowing you to interact with your application. Other Objects, like Timers, allow you to set up events to control your application. The Objects on a Card make things happen in your application. The Objects portion of the MAIN CONTROL PANEL (Pic.#3/Fig.#13) allows you to Add and Edit the Objects. 4-1 While in DESIGN Mode, either the Add or Edit Button is highlighted. This indicates the selected method of working with Objects. When ADD is selected, clicking one of the Object's Button allows you to add an Object. Each Object has an EDITOR REQUESTER which alows you to define how the Object appears and performs. While defining an Object, you give it a Name. CanDo uses the Name to identify the object. Each Object on a Card must have aunique Name. However, you can use the same Name for Objects on different Cards. When EDIT is selected on the MAIN CONTROL PANEL, clicking on a visible object (Buttons, Fields, Documents, Window Close Buttons or selecting a Menu) brings up the EDITOR REQUESTER for the Object. Alternately, clicking one of the Object Buttons in the Control Panel brings up an EDIT LIST REQUESTER (Pic.#4/Fig.#14) displaying the Names, of the selected Object Type, on the current Card. From this Requester you can Add, Edit, Delete, Duplicate and Reorder Objects. The ADD Button works just as Add from the control panel. Selecting the Add Button on the Control Panel is simply a shortcut to using the one on this Requester. The EDIT Button allows you to edit the currently highlighted Object in the list. Clicking this button brings up the EDITOR REQUESTER for the Object Double clicking an entry automatically selects Edit. The DELETE Button deletes the highlighted Object. A REQUESTER will ask you if you really want to delete the Object. Be certain that you want to delete it. The Object is disposed of completely. It does not put it in the Paste Buffer (see Object Menus). The DUPLICATE Button makes an exact copy of the selected Object. The Object will be renamed in the same manner Workbench uses in duplicateing files (ie. "copy of"). When you pres the Duplicate Button, the EDITOR REQUESTER will be displayed with the copy of the Object. This allows you to easily create similar Objects without starting from scratch each time. You can also Reorder the Objects. Visible objects, such as Buttons, can beplaced on top one another. The list shows the order in which Cando adds the Objects to the Card. Therefore, Objects that are lower in the list will appear on top in the window. The MOVE OBJECT UP Button moves an object up in the list and the MOVE OBJECT DOWN Button moves it down in the list. 4-2 Object Scripts Objects make things happen bu performing Scripts. Each Object has at least one Script that can be performed. Some can have more than one. The Object's EDITOR REQUESTER contains either a button naming each Script or a Scripts Button that will display the available Scripts. You can tell if a Script already exists when the Button is black. Clicking the SCRIPTS Button brings up the CanDo SCRIPT EDITOR. Object Menus Clicking on any area of the MAIN CONTROL PANEL (it does not have to be on a Button) allows you to access CanDo's menus using the Right Mouse Button. Under the Objects Menus, you can select from Browse, Add, Edit, Copy, and Paste. The Browse, Add, and Edit options perform in the same way as their cooresponding Buttons on the MAIN CONTROL PANEL. The Menu equivalents provide convenience in that the Amiga Shortcut Keys of AMIGA...B, AMIGA...A, and AMIGA E can be used to select them. The remaining optins are Copy and Paste. These Options allow you to Copy an Object into a Past Buffer, and to Paste it onto another Card. Selecting COPY allows you to copy an Object using two methods. First you can click on a visible Object on your card. After doing so, the previous Paste Buffer is replaced with the selected Object. Selecting one of your Menu Item copies all Menu Items and Subitems from the selected Menu into the Paste Buffer. For the second method, after selecting Copy from the Objects Meny, you click on one of the Object Buttons in the Main Control Panel. This displays the list of Object Buttons in the Main Control Panel. Double clicking an Object name, or clicking the Copy Button puts the Object into the Paste Buffer. Selecting PASTE from the Objects Menu adds the Object to the current Card. When Paste is selected, the Object's EDITOR REQUESTER will be displayed. You can then modify the Object before selecting OK, or select CANCEL to abort the Paste operation. 4-3 CanDo File Requester At various times, CanDo will display its FILE REQUESTER (Pic.#4/Fig.#15) requiring you to specify the name and location of a file. A File specification has two parts: the Path and Filename. The Path Field shows where the file is, and the File Field shows the name of the file. The smaller List on the left sets the Path. You can use it to locate the Path using Drawers, Disks, Phusical Devices, and Assignments. By default, the small list contains the list of Drawers or Sub-Directories in the directory indicated by the Path. Clicking one of its entries, sets the Path to the indicated directory. Clicking the DRAWER Button changes its name to Disks and the small list will display the available Disk Volumes. Clicking the DISKS Button changes it to Physical. The list now displays the available physical devices. Not all of these can be used for accessing files! Clicking the PHYSICAL Button changes it to Assign. Now the list shows the available assignments. (See your Amiga documentation for setting these). Finally, clicking the ASSIGN Button sets the list back to Drawer. Clicking the PARENT button changes the current Path to the parent directory if there is one. The lager List on the right, allows you to select a File Name. Clicking an entry puts the name in the File field. Double-clicking an entry selects the name as though you clicked OK. Sometimes, the FILE REQUESTER will have an additional preview button on it. For example: when you are suppose to find a picture file, there will be an additional button SHOW IT!. Clicking it allows you to see the currently selected file. When finding a sound file, the HEAR IT! Button allows you it listen to it. Clicking OK selects the current file indicated in the Path and File Fields. If the File needs to be a specific type, CanDo will verify it and display an Error Requester when it is wrong. While using the various Requesters within CanDo, you have the option of selecting Cancel or Ok. Ok accepts any changes you have made in the Requester. Cancel causes CanDo to forget any changes. Selecting either Cancel or Ok returns you to the previous Requester if there was one. 4-4 Buttons A Button is an area in a window that can be clicked with the Mouse Pointer. When clicked, specified actions can be performed. CanDo allows an unlimited number of Buttons ot be defined on the Screen. Selecting ADD in the OBJECTS PROTION OF THE MAIN CONTROL PANEL allows Objects to be aded to your application. If you click the BUTTON Button on the same panel the ADD NEW BUTTON REQUESTER will come up, direction you to locate the Origin Point of the New Button with your Mouse. Now click the OK Button. The ADD NEW BUTTON REQUESTE will be lowered revealing your full Screen. Next move your Mouse, positioning th Pointer at a location on the Screen where you want a Button. Now click the LEFT MOUSE Button to set the Origin Point. Your Mouse now controls the shape and size of a rectangle representing a Button area. Move the Mouse in any direction you choose, adjusting the rectangle until you are satisfied with its size. If you don't like the Button for some reason, press the ESC key and start over. If the Button is to your liking, click the LEFT MOUSE Button again and The BUTTON EDITOR REQUESTER (Pic.#5/Fig.#16) will be displayed. The BUTTON EDITOR REQUESTER allows you to edit the unique information about each button. It displays the Button's Name, Origin, Button Style, Border and Highlight Styles, and the avaiable Scripts. The origin coordinates of the Button, in X (horizontal) and Y (vertical) format, will have been entered for you automatically. 4-5 Name The Name is a group of characters identifying the button. The same name can not be used for more than on object on a card. The button isgiven a default name "Unknown". However, you probably will want to name it something that is meaningful to you. The Name can include any charcter. It has a maximum length of 20 characters. When you press RETURN, CanDo will verify that the name i unique. Origin The Origin always indicates the location of the upper left corner of a Button. The Horizontal value indicates the distance in pixels from the left edge of the Window. The Vertical value indicates the number of pixels down from the top of the Window. The present values can be changed by clicking in these Fields and typing in new values with the keyboard. You can also set these values using the Mouse. First click the Origin Button, and the ADD BUTTON REQUESTER will be lowered. Your Mouse now controls the position of a recangle representing the Button Area. Now move the rectangle where you want the Button to be. If, however you choose not to change your present Button you can return to the BUTTON DEFINITION REQUESTER by pressing the ESC key. When the new location looks good just click the LEFT MOUSE Button and the BUTTON DEFINITION REQUESTER will reappear. 4-6 Style CanDo has three Button styles: Area, Text and Image. When adding a Button, a rectangular area is defined. This area represents the "Hit Area" for an Area Button. Area Buttons do not have an image or text representing the Hit Area. However, they can be placed over images in the Window. In addition to Area Buttons, CanDo allows you o use Text and Image Buttons for representing Image and Irregularly Shaped Buttons. These Buttons are described in greater detail in the Text and Image sections of this manual. The check mark in the BOX next to "Area" indicates the current Button is an Area Button. Each Button style has a Requester containing unique information for its particular requirements. Clicking the BOX next to the indicated style, brings up the appropriate Requester and changes the Button style. Clicking CANCEL, aborts this process. Clicking on the BOX next to "Area" brings up a requester cdontaining information baout the size of the Area Button. This requester allows you to view or change the Width and Height of the Area Button. These values can be changed using the Keyboard. However, they can also be set using the RESIZE ON WINDOW Button (Pic.#2/Fig.#17). Clicking on this Button lowers the MAIN CONTROL PANEL. Your Mouse is now controlling the lower right corner of a rectangular box. The upper left corner is stationary on the screen. This corner indicates the Origin of the Button. The rectangular corner, and pressing the LEFT MOUSE Button a new area for the button is defined. Pressing ESC, returns to the AREA BUTTON REQUESTOR without modifying the Width and Height values (Pic.#4/Fig.#18). 4-7 Border An Area or Text Button can have a Border around its Hits Area. There are six Border Styles from which to choose. The default Border Style, Outline, is shown in the BUTTON DEFINITION REQUESTER. By clicking on the BORDER Button the BORDER SELECTOR (Pic.#5/Fig.#19), will be displayed. The BORDER SELECTOR displays the border styles from which to select. The selected syle will have a Black Hit Area. Clicking the Hit Area of the desired button selects the matching style. The bottom row contains a Cancel Button, two COLOR SELECTORS, and an OK Button. The two Color Selectors change the colors used in rendering the buttons border. The colors can be selected by using the two arrows on the Color Selectors or by clicking one of the available colors at the bottom of the Screen. The selected color is shown in the active Color Selector. Clicking on one of the Color Selectors makes it active. The sample buttons on the Border Selector depict the use of these colors. Highlight When you click on a Button that you have made with CanDo, the Button area can change to the existing color's Complementary color, or Outline the area, or do neither. The default Highlight Style, Complement, is shown in the ADD BUTTON REQUESTER. By clicking on the HIGHLIGHT Button the HIGHLIGHT SELECTOR (Pic.#6/Fig.#20) will be shown. The three Highlight Styles: None, Outline, and Complement are shown in this requester. Clicking on the associated button sets its Hit Area to Black. 4-8 Button Scripts There are four types of events that can occur by using a Mouse Button. They are Click, Drag, Release, and Double Click. Each of these events can have a Script associated with them. A script is simply a set of instructions to perform. CLICK Click events happen when the LEFT MOUSE Button is pressed while the mouse pointer is over the Button. This type of event is useful for providing immediate response to the mouse. DRAG Drag events occur as the LEFT MOUSE Button is held down and moved over the button's Hit Area. This is an uncommon type of button usage. However, these movement events can be used for tracking mouse movements in applications such as paint programs. RELEASE Release events occur when the LEFT MOUSE Button is pressed and released while over a button. This is the most common button application. By delaying until the button is released, the user can decide to move the pointer off the button, thus avioding an unwanted action. DOUBLE-CLICK Double-Click events happen when the LEFT MOUSE Button is clicked quickly two times. The Amiga Preferences allows a user to adjust the time delay used in determining a Double-Click. This type of event is used to insure that the user did not inadvertently press a button. The Icons on Workbench work in this manner. 4-9 Text Button Like an Area Button, a Text Button has a rectangular Hit Area. However, CanDo will automatically display a text message in the hit area. You specify the text massage, the font and point size, color, and style. The text is simply characters that you want to represent the action performed by the button. It can use any font avaiable in your "Fonts:" directury and can also use a varity of Text Styles, to enhance its appearance. Like an Area Button, a Text Button can have a Border around its Hit Area. An Area or Image Button can be changed to a Text Button by clicking in the BOX next to "Text" in the BUTTON DEFINITION REQUESTER. You can change the style of a Button as many times as you wish. When you have made your final choice there is one important thing to remember about this process: each Style has unique style information that must be saved. That information is saved only when you click OK on the Buton Definition Requester. The TEXT BUTTON DEFINITION REQUESTER (Pic.#6/Fig.#21) is displayed when the BOX next to "Text" is selected. A window on your screen displays the appearance of the text message. The TEXT BUTTON DEFINITION REQUESTER allow you to select the font and point size, the Text Style, the colors used, and the text message to use in the button. Notice that you don't set the size of a text button. Its size is determined automatically by the size of the message in the selected font. Selecting a Font and Point Size The available fonts in your Fonts: directory are shown in a list. A font can be selected bu clicking on its name with your mouse pointer. If you have more fonts than can be displayed in the list, the slider allows you to scroll through the list. The currently selected font is shown below the list. The point sizes available for that font are shown in the list next to the fonts. The selected size is shown below its list. When the font or size is selected, the sample text will be updated to show its appearance. CanDo uses the current Fonts: directory. Some of you may have more than one Font directory. With applications such as Paint programs, you can change directories while working on a project. This is because the font is only used while you are rendering text to the screen. Afterwards, it is not needed anymore and you can change font directorires. 4-10 Because CanDo uses the selected font when displaying a button, all fonts used by CanDo should be in the currently assigned Fonts: directory. If you change the fonts in this directory, remember to run FixFonts before using them. If the selected font can not be used, the system's default font will be used. Selecting Text Style The Amiga operation system supports Plain, Bold, Italic and Underline text style. CanDo provides enhanced styles of Embossed, Outlined, Shadowed, and Ghosted. Selecting Plain deselects all other Text Styles. Bold, Italic, and Underline can be used with each other along with one of CanDo's enhanced styles. Only one enhanced can be used at a time. The Sample text shows the results of the selected styles. Selecting Text Colors The TEXT SELECTOR has three COLOR SELECTORS. The first one is the primary color. It is used with all styles for depicting the text. The other two Color Selectors are used with the enhanced styles. The colors available in the Color Selectors are the ones currently used in your screen. Different color combinations provide different effects. Playing around with different styles and colors will give you the feel of how to use them. Selecting Text The Text defaults to the same name used for the button. However, it doesn't have to be the same. The text can be changed using the keyboard. Spaces at the beginning and the end of the text can be used to make the button larger. Selecting CANCEL does one of two things. If the Button was previously of a different Style the original Button Style will berestored. If it was already a Text Button, any changes made will be forgotten. Selecting OK accepts any change. 4-11 Image Button Image Buttons have a small picture for a Hit Area. A "DPaint" style Brush is needed to define the picture for an Image Button. Most paint packages allow a portion of a oucture to be clipped and saved in a file. These small pictures are called Brushes. CanDo allows a Brush to beused as an Image Button. When a Brush is clipped from a picture, the back ground color is transparent. While the Brush is rectangular, the Image appears to exclude this one color. CanDo supports this technique in utilizing the Brush as a Button. While the background color is drawn, it is not included in the Hit Area. This means that when the mouse is clicked on the background portion of the image, the button is not activated. This allows irregular shapes, such as arrows, to be used without including the area around the image as a Hit Area. An Image Button is created by clicking in the BOX next to "Image" in the BUTTON DEFINITON REQUESTER. This will display the IMAGE BUTTON REQUESTER (Pic.#6/Fig.#22). The IMAGE BUTTON REQUESTER allows you to select a "DPaint" style brush file for the image. The Image Name Button indicates the Name of the Brush File. By clicking the Button, you can locate the file using CanDo's FILE REQUESTER. This Requester has a Button called "Show It!" The Show It Button loads the Brush File and displays it in a Window on your Screen. This allows you to see what the brush looks like. Don't be alarmed if a large brush is not completely visible in the Window. The purpose of this feature is for you to visually verify its appearance. If it is not a valid Brush File, CanDo will display an Error message. If the Brush does not use the same display mode or color palette as your screen, it might not appear as you expect. Keep in mind that the Amiga can use only one display mode and one color palette on a single screen. However, with some planning, you shouldn't have too much trouble getting predictable results. 4-12 CanDo allows you to use the shape of a brush as the hit area, without using it's image. Clicking the BOX next to "Use Shape Only" toggles this feature. By selecting this feature, the non transparent colors in the brush image define the hit area of the button. However, the image of the brush is not rendered on the screen. This feature allows irrgularly shaped buttons to be used without changing the image on the screen. As with the AREA and TEXT BUTTON DEFINITION REQUESTER, clicking CANCEL aborts a style change or of any changes made in the IMAGE BUTTON DEFINITION. Clicking OK accepts changes and returns to the BUTTON DEFINITION REQUESTER. Alternate Image Button An Image Button, that is not using the "Use Shape Only" feature, has an additional Highlight option. Clicking on the BUTTON in the "Highlight" section of the BUTTON DEFINITION REQUESTOR, displays the HIGHLIGHT SELECTOR (Pic.#7/Fig.#23). However, this time the additional option, Alternate Image is available. Clicking on this Buton displays CanDo's File Requester, allowing you to locate the Brush File to use as the Alternate Image. The Show It Button allows you to preview the Image. It is suggested that the Brush used for the Alternate Image be of the same dimensions as the Brush used for the Image Button. Otherwise, portions of an image will not be cleared when the image changes. 4-13 Windows A Card always has a Window. The Window Object allows you to customize each Card's Window. You can change the resolution, number of colors, or provide a background image. You can also have close, resize and depth buttons. Several other options allow you to tailor the appearance of the Window. Selecting the WINDOW object from the MAIN CONTROL PANEL, brings up the WINDOW EDITOR REQUESTER (Pic.#7/Fig.#24). The Window Editor allows you to specify a Title for the Window. Along the right side of the WINDOW EDITOR REQUESTER, are four Buttons: Dimension, Window Colors, Objects, and Options. Each of these Buttons opens a Requester allowing you to control specific aspects of the Window. The Window can have four scripts associated with it: CloseButton, Resize, Deactivate, and Activate. Window Title This Field allows you to specify a Title for the Window Title Bar. If the Window Title is empty, (you can do this easily by clicking in the Field and pressing the AMIGA...X) no Title will appear. In addition, if you do not specify a close button, depth buttons, and dragbar (see Window Objects) and the Window Title is empty, the Window will not have a Title Bar. If you want to insure that you have a Title Bar, yet you don't want to have a Title, put a space in the Window Title Field. 4-14 Dimension Clicking the DIMENSION Button on the WINDOW EDITOR, brings up the DIMENSION REQUESTER (Pic.#1/Fig.#2). The DIMENSION REQUESTER allows you to specify the Window size, and number of colors. Alternatively, you can specify a Background Image. In addition, you can specify an initial position. Display Mode When providing the Width and Height, CanDo automatically determines the Display Mode. The Amiga Display modes are Low-Resolution, Extra Half-Bright, Hold and Modify (HAM), and High-Resolution. Widths up to 320 can be Low-Resolution, Extra Half-Bright, or HAM. The Display mode is determined by the number of colors. If you choose 32 colors or less you will be in Low-Resolution Mode. Choosing 64 colors produces Extra Half-Bright Mode. Finally, 4096 colors gives you HAM Mode. Widths greater than 320 requires High-Resolution Mode and can have a maximum of 16 colors. Interlace is usd with Heights greater than 200 (256 on PAL Amigas). On the left side of the DIMENSION REQUESTER, four common screen Sizes can be selected. Clicking on the appropriate Button sets the Width and Height to the indicated values. Position The X and Y values are the initial position of the Window. Most application will use default values of 0 (Zero). If the Window has a dragbar (see Window Objects), it can be repositoned with the mouse. The X value is only used when the Window is opened on Workbench (see Window Options). It indicates the initial Horizontal position of the Window. The Y value indicates the initial Vertical position. If the Window is opened on Workbench, it will be used for the vertical position of the window. Otherwise, it will be the initial vertical position of the new screen. 4-15 Picture Window Clicking the PICTURE WINDOW Button brings up the CanDo's FILE REQUESTER. The specified Image will be used as background image for the Window. The Window's size and number of colors will be determined by the picture. When a Picture Window has been selected, the Picture Window Button will be highlighted. Changing the Width or Height values, or Number of Colors will de-select the Picture Window. Clicking OK or CANCEL on the DIMENSION REQUESTER returns to the WINDOW EDITOR. Window Colors Clicking the WINDOW COLORS Button on the WINDOW EDITOR bring up the COLOR REQUESTER (Pic#7/Fig.#26). It allows you to change the color used for the Window's Background, Border and Text. These values can be set to the Color number you want to use. BACKGROUND COLOR The Background Color is the initial color of the Window. If you specify a PICTURE WINDOW in the WINDOW DIMENSION REQEUSTER, this value will not be used. BORDER COLOR This is the color for drawing the Window's border and Title Bar. If the Window does not have a border or Title Bar (see Window Options), this value will not be used. TEXT COLOR This color is used for the Window's Title. If the Window does not have a Title Bar, it will not be used. Clicking OK or CANCEL will retur to the WINDOW EDITOR. 4-16 Window Objects Clicking the OBJECTS BUTTON on the WINDOW EDITOR brings up the OBJECT REQUESTER (Pic.#1/Fig.#3). This Requester allows you to specify optional Window Objects. There are, from left to Right: Close Button, Depth Buttons, Dragbar, and Resize Button. Click on the BUTTONS of your choice. The selected object will be added to your Window. The Close Button object allow a Close Button script to be performed when clicked. The Depth Buttons allow the Window to be pushed to the back or brought to the front. The Dragbar allow the Window to be dragged. The Resize Button allows the size of the Window to be adjusted. Note: If a Resize Script exists, the Script is performed whenever the Window is resized. The Depth Buttons, Dragbar and Resize Button are most useful when used with a Workbench Window. While they are not restricted to the Workbench Window, they are used for working with more than one Window on a screen. Selecting OK or CANCEL return to the WINDOW EDITOR. Window Options Clicking the OPTIONS Button on the WINDOW EDITOR, brings up the WINDOW OPTIONS REQUESTER (Pic.#9/Fig.#28). This Requester allows you to select various options effecting the Window. The default Options are shown below. 4-17 Clicking a Button changes the option. Each Buttons toggles between two choices. The following image shows the alternative to the default Options (Pic.#9/Fig.#29). VISIBLE BORDERS The Window has an optional borde. When visible, a box is drawn around the Window using the color specified in Window Colors. If the border is invisible, the box is not drawn. BACKDROP MODE A backdrop Window means the Window is attached to the screen. The window will not have a Window Title and none of the Window Objects will be attached. If this is a Workbench Window, the window cannot be positioned on top of other windows nor can it be moved around. When the Window is opened on a Custom Screen, you will have access to the Screen Title Bar allowing the Screen to be lowered using the Mouse. BRING WINDOW TO FRONT This option effects whether the window is visible when it is opened. On a Workbench Window, the Window is allowed to be opened in front of, or behind any Windows on the screen. On a Custom Window, it affects whether the Screen is in front of or behind other Screens. You can use the WindowTo and ScreenTo Commands to change the position of the Window or Screen. 4-18 WINDOW ACTIVE The Amiga can only have one active window at a time. This Window receives keyboard input, and its menus are available to be used. The Window Activate option allows you to control whether your Window is the Active Window when it is first opened. Most of the time you will want it to be Active. However, you may wish to make a CanDo application that is started from a CLI and has a Status Window on Workbench. If you want to be able to continue typing in the CLI, without reactivating it, then you do not want your CanDo Window to become Active. WORKBENCH WINDOW This option tells CanDo to try to open the Window on Workbench. To do so, the Window must use 2 or 4 colors. In addition, if your Workbench Screen is non-interlace, the Window height can not be greater than 200 (256 on PAL Amigas). If the Window can not be opened on Workbench, CanDo will open a new screen. Clicking OK or CANCEL returns to the WINDOW EDITOR. Window Scripts The Window has four scripts that can be performed. The CloseButton, Resize, Deactivate, and Activate Scripts can be edited by clicking the appropriate Button on the WINDOW EDITOR. CLOSEBUTTON By enabling the CloseButton in Window Objects, the Window will have a CloseButton in the upper left corner. This script is performed when the button it is clicked on. RESIZE When the Window is resized, you may need to redraw your Window. Buttons, Fields, and Documents are redrawn automatically. However, all other imagery is not. This script can contain commands to redraw the imagery in the Window when it is resized. DEACTIVATE When your Window is Active, and you click in any other Window, the Deactivate Script is performed. ACTIVATE When a user re-activates the Window this script is performed. The Deactivate and Activate scripts can be used to pause an activity while the another application is being used. 4-19 Menus CanDo allows you to create menus for your applications. Most likely you're familiar with using the menus provided in most of the software on your Amiga. CanDo lets you create Amia menus with the features you have become accustomed to, and features such as Menu Images that even progessional software seldom utilizes. Features Provided in CanDo Menus * Multiple Menu Titles. * Menu Items and Subitems. * Shortcut keys. * Stylized Text Fonts. * Menu Images. * Alternate Text and Alternate Image Highlighting. Menu Components Menu Titles are visible on the Title Bar of a window when the right mouse button is pressed. They are text characters providing the context and location of the available menus. CanDo allows you to have as many Menu Titles as can be displayed on the Title Bar. When the Mouse Pointer is positioned over a Menu Title with the RIGHT MOUSE Button pressed, its Menu Iterms become visible. Each Menu Title will have at least one Menu Item. The Menu Items are the selectable list of Text or Image entries associated with a Menu Title. A Menu Item can have Menu SubItems. They become visible when the mouse is positioned over the Meny Item. Like Menu Items, they can either be represented by Text or an Image. Each Menu Item and Subitem can have a script that is executed when it is selected. In addition, they can have a Shortcut key that causes its script to be executed as though it had been selected using the mouse. 4-20 Adding and Changing Menus Menus are added and edited through Requesters. Unlike Buttons and Fields, it makes no difference whether "Add" or "Edit" is selected in the OBJECTS CONTROL PANEL. When the MENU Button is selected from the Objects Control Panel, the MENU EDITING SELECTOR (Pic.#8/Fig.#30) is displayed. The MENU EDITING SELECTOR allows the creation, deletion, reordering, and renaming of the Menu Titles. It also provides access to the Menu Items for each Menu Title. If you have two or more Menu Titles, The Movement Arrows allow you to chane their order. The top entry will appear at the far left side of the MENU BAR. The bottom entry will appear on the right side. Selecting ADD or EDIT brings up the MENU TITLE EDITOR (Pic.#8/Fig.#31). It contains the Menu Title. The Menu Title is the text that appears on the Title Bar. When EDIT is selected the Menu Title Editor will contain the name of the selected Menu Title. If you want to re-name it, simply change the name in the Field. Selecting CANCEL returns to the MENU TITLES SELECTOR. Selecting OK brings up the MENU ITEM EDITOR to the Menu Title. 4-21 Menu Items The MENU ITEMS SELECTOR works in the same manner as the MENU TITLES SELECTOR. Menu Items are created, deleted, reordered using this Selector. A Menu Title must have at least one Menu Item. If you don't Add one before selecting EXIT the Menu Title will not be created. Should you ever delete all Menu Items from a Menu Title, the Title will be removed. Choosing EDIT or ADD brings up the MENU ITEM EDITOR REQUESTOR (Pic.#10/Fig.#32). Add allows you to create a new Menu Item. Edit allows you to change on existing one. The MENU ITEM EDITOR REQUESTER allows you to define and later modify the features of a Menu Item. From this Requester, you specify the Object Name, Highlighting Style, Meny Style, and a script to be performed when it is selected. You can optionally define a Shortcut Key and menu Subitems. Menu Item Name As with other Objects, the Object Name here provides a unique group of characters identifying the Menu Item. It is the name that will be shown in the MENU ITEMS SELECTOR for the Menu Title. Menu Style Menu Items can be represented by an Image or Text. The check mark in the BOX next to "Text" indicates it as the default style. Clicking on this BOX brings up the MENU TEXT DEFINITION REQUESTER. It works the same way as the TEXT BUTTON DEFINITION REQUESTER. The Text field defaults to the Menu Item Name. However in can be altered to whatever you like. Clicking on the BOX next to "Image" brings up CanDo's File Requester. It allows you to specify the "DPaint" style Brush you want to use as the Menu Image. Clicking the SHOW IT Button will show you a representation of the Image on your Screen. As with all brush images, it uses the Screens' resolution and palette. 4-22 Menu Highlight With the RIGHT MOUSE Button depressed and the Mouse Pointer positioned over a Menu Item, it will be Highlighted. The Highlighting style is indicated in the Button below "Highlight" in the MENU ITEM DEFINITON REQUESTER. Clicking the HIGHLIGHT Button brings up the MENU HIGHLIGHTING REQUESTER. This Requester allows you to select from the available styles. Both Text and Image items can have highlighting styles of None, Outline, and Complement. The Default style is Complement. These styles work the same way as their Button Object counterparts. Text Menus have the additional Highlight Style of Alternate Text. Simply type the text into the field in the Alternate Text area of the Highlight requestor. The Alternate Text uses the same font and style as the Primary Text. Image Menus have the additional Highlight Style of Alternate Image. Clicking on the ALTERNATE IMAGE Button brings up CanDo's FILE REQUESTER allowing you to select a "DPaint" style brush file. While it is not necessary, it is suggested that the brush be of the same dimensions as the first Image used. If they are not, the image will not erase each other completely when highlighted and un-highlighted or selected and released. Selected Script A Menu Item has a single script that is performed when it is selected. Clicking on the SELECTED Button in the Script area brings up the CANDO EDITOR allowing you to edit the Script. The Menu Item is selected by pressing the RIGHT MOUSE Button and positioning the Mouse Pointer over the Item then releasing the Button. Shortcut Key CanDo allows you to assign a SHORTCUR Key to a menu item. All you have to do is type a single character in the "Shortcut Key" Field. CanDo will display the Shortcut Key symbol on the right side of the Menu Item. Pressing the RIGHT AMIGA Button and the SPECIFIED Key, performs the Menu Item's selected script as though it had been selected using the Mouse. 4-23 Menu Sub-Items A Menu Item can have a group of selectable Menu Sub-Items. By depressing the RIGHT MOUSE Button while the Mouse Pointer is positined over the Menu Item, the Menu Sub-Items become visible. The Mouse Pointer can then bepositioned over the Sub-Item you want. When the Right Mouse Button is released, the Sub-Item is Selected. To Add or Edit an existing Menu Item's Sub-Items click on the BOX next to "Sub-Item", This brings up the MENU SUB-ITEM SELECTOR. It works identically to the MENU ITEM SELECTOR. Selecting ADD, brings up the MENU SUB-ITEM EDITOR REQUESTER (Pic.#10/Fig.#33). It allows you to define the Menu Sub-Item. This definition process is the same as the MENU ITEM EDITOR REQUESTER. The only exception is that Menu Sub-Items can not have additional Sub-Items. This is a restriction enforced by the Amiga Operating System. After a menu Sub-Item is Added or Edited, clicking on OK will return you to the MENU SUB-ITEM SELECTOR. Exiting the Menu Sub-Item Selector returns to the MENU ITEM EDITOR REQUESTER. When a Menu Item has Menu Sub-Item, a check will appear in the Box next to Sub-Items. If all Sub-Items are deleted, the check will be removed. One last thing to remember: when a Menu Item has Sub-Items, it can not be selectd; only one its Sub-Items are selected. This means that the Selected Script will not be performed when the mouse is released over the Menu Item. 4-24 Fields A Field is an Area in which characters can be typed using the keyboard. CanDo provides two types of fields, Text and Integer. Text Fields allow any character, alphabetic or numeric to be entered, Integer Fields are resticted to positive or negative numeric (integer) values. Click the ADD Button in the OBJECTS PANEL to tell CanDo you want to add an Object. Next, click the FIELD Button, telling CanDo you want to add a Field. When the MAIN CONTROL PANEL is lowered, position the Mouse Pointer where you wnat the upper left corner of the Field. Click the LEFT MOUSE Button. Now when you move the Mouse Pointer, CanDo will display a rectangular box representing the Field you are creating. Now click the Mouse Button again. The Screen will display the FIELD DEFINITION REQUESTER (Pic.#11/Fig.#34). Pressing the ESC key before you define the field area, returns to the MAIN CONTROL PANEL without adding a field. This requester contains the Field's Name, Origin, Width, Border Style, Justification, Type, and the available Scripts. The Name, Origin, and Border Style work the same as in the BUTTON REQUESTER. The Name is a unique identifier for this Object. The Origin values can be altered directly with the keyboard or dynamically set using the Mouse after clicking on the Origin Button. As with Buttons, you can set the Fields' Border by clicking on the Text Button showing the current Border Style. The Font used within a Field is determined by a seting within your preferences. Most likely, you have selected 80 column text. If so, the fields will use Topaz 8. The characters in this Font have a height and with of 8 pixels. If you have 60 column text selected, the fields will use Topaz 9. Its characters have a height of 9 and width of 10 pixels. Field Width The Field's Width is shown in pixels. The number of displayable characters is this width divided by the character width of your system font. While it is not mandatory, it is best if the Field's Width is evenly divisible by the font's width EXAMPLE: If your Field is 64 pixels wide, divide 64 by 8, (64/8) = 8 4-25 The Field's Width can be altered using Keyboard, or resized dynamically on your screen using the Mouse. Clicking on the WIDTH Button, lowers the CONTROL PANEL. The Mouse controls the width of a box representing the Field. The left side of the box is fixed at the Origin. The right side is adjusted with the Mouse. When the rectangle is the desired width, click the LEFT MOUSE Button. If you don't want to resize the width, press the ESC key. Type Alignment The information in a Field can be aligned Flush Left, Centered, or Flush Right. The Default Alignment is Flush Left. This can be altered buy clicking on the button in the Alignment Area. Text Field The default Field type is Text. This is indicated by the check mark in the BOX next to "Text". Clicking on this BOX brings up the TEXT FIELD REQUESTER (Pic.#11/Fig.#35). It allows you to define the maximum number of characters in a Field, and the INITIAL TEXT. The number of visible characters is determined by the field's width. The Maximum Number Of Characters indicates the actual number of characters the field can contain. If it is greater than the number of visible characters, the contents will scroll as you type or use the arrow keys. The INITIAL TEXT allows you to specify the characters in the field when is it created. However, a user can still alter the Field's contents. 4-26 Integer Field From the FIELD DEFINITION REQUESTER, clicking in the BOX next to "Integer" will bring up the INTEGER FIELD REQUESTER (Pic.#11/Fig.#36). It allows you to specify the Maximum, Minimum, and Initial values for the Field. The INTEGER FIELD allows a user to type any valid integer. You can automatically insure that the value is within a range by specifying the upper and lower boundaries in the Maximum and Mimimum values. EXAMPLE: If you set the Maximum Value to 1000 and the Minimum Value is 50, and the user enters a value of 10, when he presses RETURN, the value is changed to 50, If you entered 1500, it would be changed to 1000. Using the Maximum and Mimimum values, Scripts can safely assume a value is within the defined range. It also provides the user with immediate feed back of the value being used. The INITIAL VALUE works similarly to the INITIAL TEXT. It provides a default value for the Integer Field. This value can be changed by the user if he so chooses. Field Scripts Fields have two types of scripts, Selected and Return. The Selected type of Script is executed when you click in the FIELD. The Return type of Script occurs when the user presses the RETURN Key. 4-27 Document CanDo's Document Object allows you to choose between a Memo editor and a List selector. The Memo editor is a multi-line text editor with optional scroll bars. It provides for free form text input and display. The NO TYPING option allows for a non-editable display. The List Selector displays a list of lines. The user of your application can choose from this list by clicking with the mouse. File Requestors use this technique to show a list of files. Both the Memo editor and the List selector use CanDo Documents. The Document commands give you flexibility in the creation and manupulation of the Document's text. These commands are described in the Scripting Commands section. As with other Objects, the Name should be aunique name for an Object for the Card. The Document field indicates the "Document name" to be used for the Object. You should read more about "Document Name"'s in the Document Scripting Commands. However, suffice it to say that this field indicates which "Document Name" to associate with this Document Object. If the "Document Name" has not already be created, CanDo will create a new one. When this is necessary, CanDo will look for a file using the "Document Name" as the file specification. If the file exists, it will automatically be loaded and displayed in the Document Object. Otherwise, an empty document will be created. 4-28 Document Type The DOCUMENT EDITOR (Pic.#12/Fig.#37) allows you to choose between Memo and List. A check mark indicates the current selection. When you click on the BOX next to Memo, the MEMO FIELD OPTIONS REQUESTER (Pic.#12/Fig.#38) is displayed. The MEMO OPTIONS REQUESTOR allows you to choose between the Scroll Bar Options. It also allows you to select the No Typing option. Clicking the BOX next to No Typing enables and disables the option. A check mark indicates that the user if your application can not type into the Memo editor. The Memo Field Editor has four Scroll Bar Options from which to choose. They are None, Horizonal Only, Vertical Only, and Horizonal & Vertical. Clicking on the appropriate Image chooses the option. Clicking the BOX next to List does not display a Requester. Document Definition Four Buttons along the right side of the DOCUMENT EDITOR REQUESTER allow you to define the Origin, Size, Font, and Border for the Document Object. 4-29 Document Origin Clicking the ORIGIN Button brings up the DOCUMENT ORIGIN REQUESTER (Pic.#12/Fig.#39). The Horizontal and Vertical Fields allow you to specify the location of the Document. The Horizontal Field indicates the number of pixels from the left edge of the window. The Vertical Field indicates the number of pixels down from the top of the window. You can reposition the document by clicking the Button SET ORIGIN ON SCREEN. Your mouse will move a rectangular box the size of your document. Position the box and click the mouse, or press ESC to abort. The Horizontal and Vertical Fields will be updated to the origin position. Document Size Clicking the SIZE Button displays the DOCUMENT SIZE REQUESTER (Pic.#12/Fig.#40). The Width and Height Fields allow you to specify the document's dimensions. These Fields show the current values. You can modify them directly. In addition, clicking the Button SET SIZE ON SCREEN allows you to dynamically set them using the Mouse. The Mouse controls the corner opposite the origin point. Adjust the size of the box and click the mouse to set the values or press ESC to abort. 4-30 Document Font Clicking the FONT Button displays the DOCUMENT FONT REQUESTER (Pic.#6/Fig.#21). The DOCUMENT FONT REQUESTER allows you to choose the Font and point size for the text to be displayed in the Document. You can also choose between Plain and a combination of Bold, Italic, and Underlined Text. Finally, you can choose the colors used for the text. The COLOR SELECTOR on the left is for the Text and the one on the right is for the background. Document Border Clicking the Border button displays the same Border Requester used for buttons. Document Scripts The Document Obejcts use the same Scripts as Buttons: Click, Drag, Release, and Double. They work in the same manner. When the user first presses the Left Mouse Button, the Click Script is performed. While thet hold the Mouse Button down and move the pointer over the document, the Drag Script is performed. When they Release the Mouse Button, the Release Script is performed. And finally, if they Double Click on the document, the Double Click Script is performed. 4-31 Timers CanDo has two types of timers: Interval and Alarm. Interval Timers go off after alength of time has elapsed. Alarm Timers go off at a specified time of day. When a Time goes off, the Occrred Script is performed. The TIMER EDITOR REQUESTER has two forms. Someof the titles and buttons are changed when selecting between Interval and Alarm Timer. Interval is the default setting. It is indicated by the check mark next to "Interval". An Interval Timer can go off once after the elapsed time or it can be Reoccurring. This causes it to occur repetitively after the each interval. A Reoccurring Interval Timer, with a short elapsed time, can cause seemingly continuous activity while allowing other Object's Scripts to be performed if necessary. When Interval is specified, the TIMER EDITOR REQUESTER (Pic.#13/Fig.#42) allows you to specify the time interval and whether or not the timer is re-occurring. The time interval is specified in Minutes, Seconds, and Jiffys. Jiffys are fractions of a second. On NTSC Amigas, the U.S. standard, Jiffys are 1/60th of a second. On PAL Amigas, Jiffys are 1/50th of a second. The values can be set directly using the keyboard, or moditied using the increment / decrement Buttons next to each field. Clicking the BOX next to "Reoccurring", causes the Interval Timer to repeat continuously. For example: If the interval is set to 2 seconds, 00:02:00, the Occurred script will be performed every 2 seconds. Clicking the BOX next to "Reoccurring" toggles it On and Off. A check in the box indicates that it's on. 4-32 Clicking the BOX next to "Alarm" indicates the Timer should go off at a specified time. The ALARM TIMER can be set to occur every day or on a specific day of the week (Pic.#13/Fig.#43). The Hour, Minute, and Second Fields let you indicate the Time for the Alarm. These times can be set using the keyboard, or they can be set using the Buttons next to each Field. The Alarm's Day Segment can be set by clicking the Buttons AM or PM which toggle between the two. Alarm Timers can be set for every day or for a specific day of the week. The default setting is Every Day. By clicking the DAY OF THE WEEK Button, it cycles through each day of the week and Every Day. 4-33 Sounds The CanDo Sound Object allows you to synchronize other sounds and graphics with a sound. The Sound Object does NOT play the sound. It simply allow you to perform scripts when a specified sound starts or finishes playing. While it does not play the sound, it does load it into memory, if it is not already loaded there. When adding or editing a Sound Object, CanDo will display the SOUND EDITOR REQUESTER (Pic.#14/Fig.#44). Clicking the BUTTON next to "Sound To Wait For" brings up CanDo's FILE REQUESTER allowing you to locate the sound associated with this object. If must be a valid 8SVX sound. 8SVX is the IFF sound standard supported by the Amiga. Also on the FILE REQUESTER, you can press the HEAR IT! Button to preview the sound. After pressing OK, the SOUND EDITOR REQUESTER will reappear and display the name portion in the "Sound To Wait For" Button. The Sound Object waits for the specified sound to begin or finish playing. Any script on the current card can play the sound using the PlaySound or PlaySoundSequence Commands. However, they must use the exact same file specification as the "Sound Name". If the same sound is played using a different file specificaton or "Sound Name", the Sound Object's scripts will not be performed. Scripts A sound is played using the PlaySound and PlaySoundSequence Commands (see the Sound Editor Tool and Sound Commands). Whenever the specified sounds begins to play, the Start of Sound script is performed. When the sound is completed, the End of Sound script is performed. 4-34 Animation CanDo allows you to display DPaint III style BrushAnims. The Animation Object does NOT display the BrushAnim. It simply allows you to perform scripts at specific points in the animation. This lets you coordinate other activities with the animation. Selecting the Animation Button form the Main Control Panl, brings up the BrushAnim Editor Requester (Pic.#14/Fig.#45). An Animation Object works with a single BrushAnim. The Animation Object's Scripts are triggered by the specified BrushAnim's activities. If you want Scripts associated with two BrushAnims, then you need to make two Animation Object's. Clicking on the FILENAME Button brings up CanDo's File Requester allowing you to locate a DPaint III style Brush Animation. Clicking the SHOW IT! Button allows you to preview the animation. Scripts The Scripts for the specified BrushAnim can never be performed unless it is being displayed. The ShowBrushAnim Command can be performed in any Script except for a Card's StartUp Script. If you want it to be shown when you to a Card you should put it the AfterStartUp Script. See BrushAnim Scripting Commands for more details. The Animation Objects allows you to perform a Script on each frame of an animatin, on specific frames, or when a moving BrushAnim reaches a Destination. 4-35 Every Frame This Script is performed before each frame of the animation is shown. Depending on how long you make this Script, the animation may be slowed down drematically. Destination This Script is performed when the animation reaches the destination of a MoveBrushAnim or MoveBrushAnimTo Command. BrushAnim Frames... Individual Scripts can be performed before specific frames are shown. THE LIST REQUESTER shows the frame numbers for which there is a Script. The Buttons on the right hand side allow you to Add, Edit, and Delete Scripts from the list. Clicking ADD displays the BRUSHANIM FRAME REQUESTER (Pic.#12/Fig.#46). It has a Slider allowing you to quickly choose the Frame Number. The selected Frame is shown in the Frame Field. You can also enter the Frame directly into the Field. If you click OK, the CANDO SCRIPT EDITOR will be displayed. When you finish creating the Script, the BRUSH ANIM EDITOR will be re-displayed. 4-36 Disk CanDo provides a way of performing a Script when a diskette is removed from or inserted into the disk drive. This can be a fun way of playing different sounds when disks are removed and inserted. While it is not usually necessary, your application can monitor the available volumes. The Disk Object provides a way of performing these tasks (Pic.#15/Fig.#47). The Disk Object has two Scripts. Disk Removed and Disk Inserted. The scripts are performed whenever a diskette is removed or inserted from any drive. 4-37 Routines Routines allow you to write a Script that can be performed by any Object. When creating the Routine, you give it a Name. The Script is performed using the Do Command with this name (see documentation on the Do Command for more details). Unlike other Objects, the Routines Object is global to all Cards. This means that a Routine is accessible from every Card in your Deck. Routines keep you from having identical Scripts in different Objects. When you want multiple Objects to do the same thing, simply put the common scripting commands in a Routine. You can then access the Routine from any Object's Script using the Do Command. The ROUTINE EDITOR (Pic.#16/Fig.#48) has a field for the Routine's Name. The Do Command uses this Name to access the Script. When using the Do Command, put the Name in double "the name" qoutes. The Script Button allows you to write the Routine's Script. The Script can contain Do Commands. While it is valid for a Routine to Do itself, you should not try this unless you are familiar with the advanced programming techniques. It is very easy to create an endless loop that uses all remaining memory. 4-38 ARexx Your application can listen to one ARexx port at a time. This port is specified using the ListenTo Command (see ARexx Commands for more information). Other Applications can send messages to this port. Amessage is simply an ASCII string. The first word of the message is the Command Word. When a message is received, CanDo uses the Command Word to see if you have ARexx Object that corresponds to it. If there is one, its Occurred Script is performed. Clicking the AREXX Button on the MAIN CONTROL PANEL, brings up the AREXX EDITOR REQUESTER (Pic.#16/Fig.#49). The Object's Name Field is initially empty. If you do not fill it in, it will automatically be set to the word you put in Message Field when you press the OK Button. The Message Field should contain a single word indentifying the message's Command Word. When a message is received, and its Command Word matches the word you put in this Field, the Occurred Script is performed. The script can then use the System Variable TheMessage which contains the complete text of the message just received. By making a series of ARexx objects, one for each Command Word that can be performed by your application, you can very easily create a complete ARexx server. 4-39 Xtras This Objects portion of the MAIN CONTROL PANEL contains the core group of Objects supported by CanDo. As more Objects are added, they will be accessible through the Xtra's Button. In addition to Objects, the Xtras give you access to expanded operations. These Operations can also beaccessed through the Xtra's Button. Each CanDo Xtra has a file in the Xtra directory. As additional Xtras become available, you simply put its file in the Xtras directory. Because the Xtra Objects and operations are not individually documented in this manual, there will be documentation files on the disk. Pressing the XTRA Button on the MAIN CONTROL PANEL brings up the XTRA SELECTOR (Pic.#16/Fig.#50). This Selector contains a list of the available Xtras. Simply DOUBLE CLICK an entry or click the PERFORM Button. When you do so, the selected operation will be performed. You should make sure you are familiar with what the Xtra is going to do by reading its documentation. 4-40 Chapter 5 Script Editor Every Object has at least one Script that can be performed. By clicking a button on the Object's Editor Requester, you can edit the Script using CanDo's Script Editor. The Script contains Commands telling CanDo what you want to happen when the Script is performed. CanDo's Scripting Commands are described in Chapter 6. This Chapter describes how to use the Script Editor and Editor Tools. Menus The Script Editor works like most text editors. Using the keyboard and cursor keys you can type in your script. The vertical Slider on the right lets you scroll through a script. The Editor has four Menus: Script, Text, Edit, and Misc. Some of their Menu Items have SHORTCUT Keys. These Menu functions can be invoked using the RIGHT AMIGA Key. Script Menu The Script Menu contains: OK, CANCEL, VERIFY, CLEAR, and PRINT. OK OK verifies the script and returns to the CanDo requester from which you invoked the Script Editor. If the script contains an Syntax Error, a requester will indicate nature of the error. When you select Continue, the cursor will be placed af the beginning of the problem line. CANCEL Cancel returns to the previous requester without including any changes made to the script. VERIFY Verify checks the syntax of the scirpt. Although this is done automatically when you select OK, this option allows you to verify the script without leaving the Scripting Editor. If an error is detected, a requester will indicate the error and your cursor will be move to the beginning of the line containing the error. CLEAR Clear erases all lines in the Script Editor. Should you inadvertently clear a script, select Cancel and re-invoke the Script Editor. PRINT Print sends the entire contents of the Script Editor to the Printer. 5-1 Text Menu The Text Menu allows you to Load, Save, and Insert text. LOAD Load replaces the contents of the Script Editor with the contents of a Fil. Cando's File Requester allows you to locate the file. SAVE Save writes the contents of the Script Editor to with CanDo's File Requester, and inserts it into the Script at the currently exists, it will be replaced. INSERT Insert takes the contents of a file, specified with CanDo's File Requester, and inserts it into the Script at the current cursor position. Unlike Load, it does not first clear the existing script. Edit Menu The Edit Menu allows you to Search For and Replace text in the Script. SEARCH Search... searches for the next occurrence of a text string. A requester allows you to specify the string to search for. SEARCH NEXT Search Next searches for next occurrence of the last text string specified with Search... REPLACE Replace... searches for the next occrrence of a text string and repleaces it with another. A requester allows you to specify the Search string and the Replace String. REPLACE NEXT Replace Next repeats the last Replace... operation without bringing ip the Search/Replce Requester. REPLACE ALL Replace All replaces all occurrences of a text string with another. Misc. Menu The Mics. Menu contains: Help, Delete Line, Delete to EOL, and Undelete Line. HELP Help brings up the Scripting Help Requester. This Requester is described later in this Chapter. DELETE LINE. Delete Line erases the current line. It can be restored using Undelete Line. DELETE TO EOL Delete to EOL erases all characters from the current cursor position to the end of the line. The characters can be restored using Undelete Line. UNDELETE LINE Undelete Line restores the characters erased by the last Delete Line and Delete To EOL. 5-2 Shortcut Buttons Six of the Menu Items have a shortcut button located at the top of the Scripting Editor: OK, Cancel, Search..., ...Next, Replace..., and Help. These buttons work the same way as their menu counterparts. Scripting Help You can get help on CanDo's Scripting Commands, Functions and System Variables through the SCRIPTING HELP REQUESTER (Pic.#15/Fig.#52). If is invoked by selecting the Help Menu Item under Misc., by clicking the HELP button, or double clicking a word in your script. CanDo will try to give you help for the word under the cursor or for the first word on the line. The main area of the requester displays the help message. When there is more information than can be displayed in the message area, you can use the NEXT PAGE Button to move forward. The PREV PAGE Button can then allow you to move backwards. Some of the words in the message area can be clicked on for additional help. You can identify these words because they will be in Red. By clicking on a RED WORD, a related help topic will be shown i place of the one which you are currently reviewing. When you want to return to the previous help topic, press the BACK Button. If you have moved several levels from your original Help Message, you can return to the first one by pressing the TOP Button. The Topics, Commands, Functions, and Variables Buttons allow you to look up other Help Messages. By pressing one of these Buttons, the list on the right will contain a selection to choose from. Pressing the TOPICS Button displays a list of Topics such as Graphics and Card Movement. When you select one of the listed Topics, the lister will the display all of the Commands for the Topic and the COMMANDS Button will be highlighted. Clicking on one of the Entries in the list, displays its Help Message. By clicking the FUNCTIONS Button, the list will display the Functions for the Topic. Clicking the VARIABLES Button shows the System Variables. When you are ready to return to the Script Editor, press the Exit Button. 5-3 Editor Tools Along the right side of the Script Editor is a selection of Editor Tools. These Tools allow you to interactively create scripts. For beginners, this is an easy way to get started without spending too much time learning Scripting Commands. In fact, using the Editor Tools can be the easiest way to learn. By using them to create your own "examples", you can learn both specific Commands and the way CanDo's Scripting Commands work in general. Advanced Users can create a "rough" script performing some of the tasks they want to accomplish. By changing a few constants to variables, and adding a loop, or other such modifications, it can be very easy to create sophisticated scripts. Some Tools make it easy to access things that CanDo "knows" about. Card, Routine, and File Names, to name a few, are more easily and accurately identified using Editor Tools. Other Tools simply let you see the results before you try it out. When you click on one of the Icons, a specialized requester will help you in creating your script. Feel free to just play around with the Tools. However, you should be familiar with CanDo's ARexx capabilities befoe exploring the ARexx Editor Tool. 5-4 Paint Editor Tool The Paint Editor Tool works like a small paint program. By using its Tools, you can draw in the window and it will create the necessary Scripting Commands. By selecting the PAINT EDITOR TOOL ICON (Pic.#18/Fig.#53), CanDo will display the EDITOR TOOL PANEL. At the very bottom a color bar will display the current color palette. The Paint Editor Tool is designed to look and feel like a simple painting package. You simply select a drawing Tool, a color to use, and draw in your window. While it may seem like a paint program, you need to be aware that you are creating a Script. Each action you take generates Scripting Commands. It is very easy to create large Scripts using this Tool. 5-5 Dots and Continuous dots and Drawing Lines These Tools allow you to draw in a series of dots or small connected lines. Simply select a color and draw using the LEFT MOUSE Button. You should keep in mind that these Tools can easily create large Scripts. The Line Tool allows you to draw a line in the window. Simply position the mouse pointer, press and hold the LEFT MOUSE Button, move the mouse pointer and release the Mouse Button. A line will be draw between the two points. Flood Fill The Flood Fill Tool allows you to fill an enclosed area with the selected color. Position the mouse pointer on your window and click the LEFT MOUSE Button. Triangle and Area Triangle These Tools allow you to draw triangles. The Triangle Tool draws with lines, and the Area Triangle Tool draws filled Triangles. Simply define one side of the triangle in the same manner as drawing a line. When you release the mouse button, the pointer will control the position of the third vertex. Position the pointer and click the LEFT MOUSE Button. Parallelogram and Area Parallelogram These Tools allow you to draw parallelograms, a four sided polygon with parallel lines. The Parallelogram Tool draws with lines, and the Area Parallelogram Tool draws with a solid color. Draw a line by positioning the mouse pointer at the first vertex, press and hold the LEFT MOUSE Button, and drag the mouse pointer to the second vertex and release the Mouse Button. The Mouse pointer will now control the three remaining sides. As you move the pointer, a parallelogram will be formed. When you press the Mouse Button again, the final image will be displayed. Rectangle and Area Rectangle These Tools allow you to draw a rectangle with lines or a filled block. Position the Mouse pointer, press and hold the LEFT MOUSE Button to define on of the corners. While holding down the Mouse Button, drag the pointer to the opposite corner and release the Mouse Button. Circle and Area Circle Using these Tools, you can draw filled or unfilled circles. These Tools do not automatically adjust the radius for all screen dimensions. However, you can use the ellipse Tool for these situations. Position the Mouse Pointer then press and hold the LEFT MOUSE Button. This defines the cente of the ellipse. While holding the mouse button, drag the pointer to define the size of the circle and release the Mouse Button. Ellipse and Area Ellipse These Tools allow you to draw filled or unfilled ellipses using the currently selected color. Position the Mouse Pointer and press the LEFT MOUSE Button. This defines the center of the ellipse. While holding the Mouse Button down, drag the pointer to define the size and shape of the ellipse and release the Mouse Button. Brush Clip This Tool copies a rectangular area of the current window so it can be used be the Draw With Brush Tool. Simply positon the Mouse Pointer to one of the corners and press the LEFT MOUSE Button. While holding down the left mouse button, drag the pointer to the opposite corner and release the mouse button. The Draw With Brush Tool will automatically be selected. 5-6 Draw with Brush This Tool draws with a clipped brush created using the Brush Clip Tool. CanDo will not allow you to select this Tool if you have not previously clipped a brush. When this Tool is selected, you will see the clipped image as you move the mouse pointer. Simply position the image and click the LEFT MOUSE Button. Draw-Mode The Draw-Mode Button toggles between Normal and Complement (Pic.#17/Fig.#54). While in Normal Mode, the drawing Tools will draw using the currently selected color. While in Complement Mode, the drawing Tolls will completement the colors over which they are drawing. The advantage of Complement Mode is that when the script is repeated, the drawing will Complement back to what is was. Multi-Mode The Multi-Mode Button toggles on and off. When it is off, drawing Tools will draw a singe image. When it is on, the Line, Triangle, Parallelogram, Rectangle, Circle, and Ellipse Tools will draw multiple images. Clear The Clear Button clears the window. Remember, this plaecs a ClearWindow Command in the Script, and is not the same thing as starting over. Undo The Undo Button will undo previous operatons. Each time you press the Undo Button, the last operaton will be forgotten, and all remaining operations will be re-displayed, This can be repeated until all operations have been forgotten. This provides the unique feature of unlimited undo's. However, you need to keep in mind that you are removing Scripting Commands. 5-7 Selecting a Color The COLOR SELECTOR (Pic.#17/Fig.#55) displays the current drawing color. You can use the up and down arrows to step through the available color, or simply click on the color in the COLOR BAR. The PALETTE SLIDERS allow you to change a color. Remember, changing a color generates a Scripting Command. It does not change the initial Palette. Rather, it changes the color when this Script is performed. NOTE: You should avoid changing the colors in a Workbench window. Text Editor Tool The Text Editor Tool helps you print text in your window. When you select the TEXT EDITOR TOOL ICON, the TEXT EDITOR TOOL REQUESTER will be displayed. Selecting the SET TEXT AND FONT... Button brings up the TEXT AND FONT REQUESTER (Pic.#16/Fig.#56). This requester works in an identical fashion to the TEXT BUTTON DEFINITON REQUESTER described on Page 4-10. After setting the Text and Font, click the SET POSITION... Button. This will allow you to position a representation of the text using the mouse. Click the LEFT MOUSE Button when it is positioned where you want it to be. 5-8 Sound Editor Tool The Sound Editor Tool helps you play sounds. CanDo supports the playing of 8SVX digitized sound files, the standard supported by the Amiga. This Tool helps you select a sound, volume and audio channel. Selecting the SOUND EDITOR TOOL ICON brings up the SOUND EDITOR TOOL REQUESTER (Pic.#16/Fig.#57). This Requester allows you to choose from three options: selecting a sound file, changing the volume, and selecting an audio channel. You can choose one or more of these options. CanDo will produce the Scripting Commands for the options you choose. For example, you can select a sound File and a channel and not choose a volume. Clicking the SET THE FILENAME... Button brings up CanDo's FILE REQUESTER. You can use it to locate the sound you want to play. When you select OK, CanDo verifies the File is an 8SVX digitized sound, and returns you to the SOUND EDITOR TOOL REQUESTER. Selecting the SET THE VOLUME... Button brings up the SET VOLUME REQUESTER (Pic.#15/Fig.#58). This Requester has slider and a field you can use for selecting the volume level. The slider is scaled from 0% to 100%. As you move the slider, the value in the Volume Field will show the equivalent volume setting. This value ranges from 0 to 64. You can also set this value using the keyboard. When you select OK, the SOUND EDITOR TOOL REQUESTER is re-displayed. NOTE: When you change the volume setting, all subsequent sounds will be played at the selected volume. 5-9 Selecting the SET THE CHANNEL... Button from the SOUND EDITOR TOOL REQUESTER brings up the SET CHANNEL REQUESTE (Pic.#17/Fig.#59). This Requester allows you to specify a specific audio channel on which to play a sound. If you do not select a channel, the sound will play on the next available sound channel. By chosing a specific audio channel, you can control which speaker the sound is played on. Audio channels 0 and 3 are played on the left side, and channel 1 and 2 is played on the right side. However, if the specified audio channel is being used when the Script is performed, the sound will nut be played. When you select one of the four Buttons, it will become highlighted. When you select OK from the SET CHANNEL REQUESTER, you will return to the SOUND EDITOR TOOL REQUESTER. Remember, whatever you are using the SOUND EDITOR TOOL REQUESTER, you can select OK and CanDo will return you to the SCRIPT EDITOR. CanDo will produce the Scripting Commands for the options you have selected up to that point. Picture Editor Tool The Picture Editor Tool helps you locate a Picture and creates the Command to show it. When you select the PICTURE EDITOR TOOL ICON, CanDo's FILE REQUESTER will allow you to find the picture file. When you select OK, CanDo will create the Command to show the picture. 5-10 DOS Editor Tool The DOS Editor Tool helps you Run another program. When you select the DOS Editor Tool Icon, CanDo's File Requester will appear. Locate the program you want to run, and press OK. CanDo will verify it is an executeable program. This Tool creates a DOS Command. It simply tells the Amiga Operating System to execute the program within the quotes. The Editor Tool puts the word "c:Run" in front of the program you selected. FOR EXAMPLE: DOS "C:RUN C:DIR" This allows your CanDo application to continue running after is starts the selected program. If you want your CanDo application to wait until the selected program is done, you can remove the word "C:RUN" from the command. DOS "C:DIR" Some programs allow parameters to be passed on the command line. You can do this by adding them after the selected program. DOS "C:DIR >RAM:WORKFILE" This final example would execute the Dir command in the C: directory. It does not have a "RUN". Therefore, your CanDo application will wait until the command has completed before continuing. Finally, it tells the Dir command to save its output in a file called "RAM:WORKFILE". File Editor Tool The File Editor Tool helps you to locate a file using CanDo's File Requester. It does not create a complete Scripting Command. It simply returns the file specification enclosed in double qoutes. Many of CanDo's Commands use a file specification in this form. This way, you can use the File Editor Tool to locate the file for one of these Commands. Coords. Editor Tool The Coordinates Editor Tool allows you to find the x,y coordinates of a location on your Window. When you select the Coordinates Editor Tool Icon, you should move the cross-hairs to the location you want and press the Left Mouse Button. This Editor Tool does not create a complete Scripting Command. It simply returns the horizontal and vertical values for a single location. Many of CanDo's Scripting Commands use these x,y values. You can use this Editor Tool for finding x,y coordinates for one of these Commands. 5-11 Card Finder Tool The Card FINDER EDITOR TOOL helps you with Card Movement Commands. Selecting its Icon displays the CARD FINDER REQUESTER (Pic.#19/Fig.#60). This Requester has Buttons on the left side for each of the options, and a list of all Card Names on the right side. This list works in conjunction with the first two options, inserting the Card Name and inserting a "Goto". By clicking on one of the entries, the Name is placed in the Card Name Field. After selecting a Card Name, pressing the INSERT THE NAME OF THIS CARD Button returns you to the Editor. The selected Name will be typed into your Script. Selecting one of the four Buttons at the bottom, FIRST, PREVIOUS, NEXT, and LAST, inserts a single Scripting Command. These Commands do not use the selected Card Name. Routine Editor Tool The Routine Editor Tool displays a list all the Routine names and allows you to insert the Name or a "Do" Command for the Routine. When you select the ROUTINE EDITOR TOOL ICON, CanDo will display the ROUTINE FINDER REQUESTER (Pic.#17/Fig.#61). The ROUTINE FINDER REQUESTER displays a list of all currently defined Routines in a list on the right side of the Requester. By clicking on one of the entries, its Name will be placed in the Routine Name Field. When you select the INSERT THE NAME OF THIS ROUTINE Button, CanDo will put the Routine Name, enclosed in quotes, into your Script. When you select the INSERT A "DO" TO THIS ROUTINE Button, CanDo will put a Do Command into your Script. 5-12 Field Editor Tool The Field Editor Tool helps you with the Field Object. The Field Object allows the user of your application to enter or otherwise edit a single line of text or an integer number. You can set or retrieve the contents of a Field using Scripting Commands. This Editor Tool assists you in doing this. Selecting the Field Editor Tool Icon displays the FIELD EDITOR TOOL REQUESTER (Pic.#19/Fig.#62). This Requester displays the Object Name for all Fields on the current card and gives you three Scripting options. You can simply insert the Object's Name, set the contents of the Field, or retrieve the contents of the Field. Selecting a Name Each Field is given a Name on the FIELD EDITOR REQUESTER. The Names for all Field Objects are displayed in the list on the right side of the FIELD EDITOR TOOL REQUESTER (Pic.#19/Fig.#62). By clicking an entry, the Name will be put into the FIELD NAME Field. You should select an entry by clicking one of the three Scripting options. Insert Field's Name Clicking the INSERT THE NAME OF THIS FIELD Button automatically types the selected Object Name with double qoutes on each side. This is a simple way of finding a Field Name and using it with a Scripting Command. This option does not produce a complete Scripting Command. 5-13 Set Field's Contents Clicking the SET THIS FIELD'S CONTENTS TO... Button displays the SET FIELD REQUESTER (Pic.#17/Fig.#63). The New Value Field allows you to type in a value to be put in the selected Field. If the selected Field is an Integer Field, you will be limited to entering a valid integer value. Otherwise, you can enter any characters you wish. Remember, if you want to include any double qoutes, you should put two in a row (""). Selecting OK creates the necessary Scripting Command and returns you to the Editor. Put in a Fields Contents Selecting the PUT THIS FIELD'S CONTENTS INTO... Button displays the GET FIELD REQUESTER (Pic.#19/Fig.#64). This Requester aids you in retrieving the contents of a Field and putting the value into a variable. You need to provide the Variable Name on the provided Field. Clicking OK creates the necessary Scripting Command and returns you to the Field Editor Tool. 5-14 ARexx Editor Tool The ARex Editor Tool helps you send and receive ARexx messages. If you are interested in doing this, it si recommended that you read both the ARexx Object and ARexx Commands sections before doing so. While this Editor Tool makes it easier to produce the ARexx Commands, you should first familiarize yourself with the ARexx concepts. Before sending ARexx messages to an application, acquaint yourself with its ARexx capabilities. It should have documentation for its ARexx Port Name and the Commands it can receive. After selecting the AREXX EDITOR TOOL ICON, CanDo will display the AREXX EDITOR TOOL REQUESTER (Pic.#20/Fig.#65). From this Requester you can select a Message Port to listen to or speak to, or send an ARexx Message to the current SpeakToPort. ListenTo Selecting the SELECT A MESSAGE PORT TO LISTEN TO... Button, displays the LISTENTO REQUESTER (Pic.#20/Fig.#66). This Requester allows you to specify the ARexx Port Name that your application uses to receive ARexx messages. It is recommended that you put this in the StartUp Script of your first Card. Selecting the INSERT THE "LISTENTO" Button inserts the Command and returns you to the Editor. 5-15 SpeakTo Selecting the SELECT A MESSAGE PORT TO SPEAK TO... Button from the AREXX EDITOR TOOL REQUESTER displays the SPEAKTO SELECTOR (Pic.#20/Fig.#67). The SPEAKTO SELECTOR displays all of the Public Message Ports. While an ARexx Port is Public, not all Public Ports can receive ARexx messages. In fact, sending a message to some ports will cause the Amiga to crash. You should know the Name of the Port to which you wish to send a message. This Selector simply makes it easier for you to find the Name and insure that it is currently available. Clicking an entry selects the Name and puts it into the Port Field. Selecting the INSERT THE "SPEAKTO" Button or double clicking an entry inserts the Command and returns to the Editor. Send Message Selecting the SEND AN AREXX MESSAGE Button from the AREXX EDITOR TOOL REQUESTER displays the SEND AREXX MESSAGE REQUESTER (Pic.#21/Fig.#68). This requester allows you to send a message to the current SpeakToPort. Simply enter the message and click the INSERT THE "MESSAGE" Button. This will insert the SendMessage Command and return you to the Editor. 5-16 Chapter 6 Commands CanDo has over 200 scripting Commands and Functions. However, you shouldn't feel as though you need to know how to use all of them in order to make your application. In fact, you really only need to know a few to get started. You should use the Editor Tools to get your feet wet. By looking at the Commands they produce, you can learn a great deal about the way the Commands work. At first you will want to use this Chapter as a reference for the Commands your encounter. As your needs grow, you will want to read about a certain cleasses of Commands. This Chapter is organized for this purpose. Each section describes certain aspects or classes of Commands. While you do not initially have to understand Expressions and Functions, you should eventually read the first two sections of this Chapte. By making use of Expressions and Functions, you can easily add a lot of sophistication to a simple application. The FlowControl and CardMovement Commands are very powerful. They allow you to change what is happening in your application. The CardMovement Commands, in particualr, are very simple and you should learn to use them early on. The Graphic, Screen and Window, Animation, and Audio Commands are the spice you use in your CanDo applications. However, these comprise the majority of the Commands and they amy take little while to master. Keep in mind that you don't have to learn to use everything. If something seems complicated, come back to it later. The Document Commands are unique. You can use them with the Document Objects or for internal manipulation of text. These Commands bring an additional level of power to the manipulation text. Depending on your needs, you may not want to work with these initially. File I/O, Icons, ARexx, Object and Buffer Commands should be considered advanced. Power users can use these Commands to make applicatons that rival professional software. Finally, Mics. Commands rounds off a few Commands that you may find useful in your application. 6-1 Command Symbols There are several symbols used in describing the various Commands and Functions. < > are used to indicate Integers. * " " are used for Stings. * « » are used for Logicals. * { } are used to show optional parameters are Optional. , a Comma separates parameters. ; end of a Command line. KEYWORDS are always shown in all capital letters. * You should read the Expression System sectoin for an explanation of Integers, Strings and Logicals. 6-2 Expressions An expression is a group of constants, variables, and functions combined with operators. You use expressions to tell CanDo's scripting commands what to do. Most of the time, you will use constans such as 5,"Hello", and ON. However, sometimes you will want to do more sophisticated operations. Expressions allow you to describe a value that is determined at the time the command is performed. Cando's expression system has been designed to be as intuitive as possible. Numbers are represented as integer constants. Strings are contained in double "quotes". And logical values use names such as ON, OFF, YES, NO, TRUE, and FALSE. In addition, you can mix integer, string, and logical values within expressions, and CanDo will automatically convert the values as needed. This section describes the details of CanDo's expression system. While it is not necessary for you to understand all aspects of this system, CanDo provides many sophisticated operations and functions. Depending upon your experience level, you may want to use this as a reference section or you may want to read it for a complete understanding of CanDo's expression system. Either way, you should at least scan it to get a grasp of its principles and abilities. Most of CanDo's scripting commands use expressions to provide the information for the operaton. For example, the LET command saves a value in a variable. The format for LET command is: LET VariableName = expression. The results from evalution the expression is saved in the indicated variable. Example: LET X = 100 In this example, 100 is a simple expression containing a single integer constant. It is saved in the variable 'X'. LET Y = X * -2 The expression in this example is 'X * -2'. The result, -200, is assigned to the variable 'Y'. LET Z = 5 + ABSOLUTE ( Y + 10 ) This expression uses the ABSOLUTE function. A function takes one or more parameters within parenthsis, performs an operation, and returns a single value. Each parameter within a function can be an expression. The parameter for the ABSOLUTE function, in this example, is the expresson 'Y + 10'. As you might expect, the ABSOLUTE function returns the absolute value of an expression. The absolute value of the expression '-200 + 10' is 190. 'Z' is assigned the value of '5 + 190', or 195. 6-3 An Expression is a combination of constants, variables, and functions with operators for computation. The evaluation of an expression results in a singel value. Within CanDo, expressions use three types of values: Integer, Strings and Logicals. Integers Integers are the basic numeric system for dealing with graphics and computer control. Integers are whole numbers that range from -214.783.648 to 214.783.648. An integer constant is a series of digits. A minus sign preceding the digits indicates a negative integer. A plus sign is not necessary to indicate a positive integer. However, it can be used to provide clarity. Examples: 105 -5000 +6 Strings Strings are groups of characters. String constants are characters contained within double quotes. For example: "Fred is Here". However, the double quotes are not part of the string. They simply show where the string begins and ends. Strings can be as large as available memory will allow. Or a string can be empty. An empty string is often referred to as a null string. CanDo recognizes a null string as two double quote marks "". Strings can contain any character. These include many that are not visible or are considered part of the International characte set. For a string to contain a double quote, it must be typed twice within the string. CanDo will teat is as though only one is contained in the string. For example "Fred says""Hi"" th everyone." contains the word "Hi" within the string. Logicals Logicals (known as Booleans) simply mean true of false. The words TRUE and FALSE are logical constants. Within CanDo, YES and ON also mean TRUE. Similarly, NO and OFF mean FALSE. Variables A variable is a name to be used in the place of an integer, string, or logical constant value. Variables can be thought of as storage locations for values. CanDo does not require you to 'declare' a variable. Variable names may contain letters, digits, and underscore character (_). The name must begin with a letter. The names can be any length. However, longer names use more memory and take longer to identify. Any variable name can be used for integers, strings, or logicals. 6-4 LET LET VariableName = expression The LET command allows you to save a value in a variable. CanDo evaluates the expression and then saves the value in the variable. This value will be used in the evaluation of expressions containing the variable. CanDo also provides system variables and functions such as 'MouseX' and 'Sign (expr)'. With the exception of these variables and functions, any variable name can be used. Expressions An expression contains constants, variables, and functions that can be combined with operators to form a new value. An example of a simple expression is 'Count + 5'. The first value, 'Count', is a variable. The second value, '5' is an integer constant. The '+' represents the addition operator. This expression adds the constants of the variable 'Count' with 5. Constants, variables, and functions can be used interchangebly as values within an expression. An operator is a symbol that represents a process to be performed on one or two values. CanDo allow any type of value to be used with any operator. Strings, integers, and logicals can be used interchangeably with any operation. Each is automatically converted to the type of data used by the operator. Examples: "-1000" + 5 The additon operator (+) adds two integer values. The first value, "-1000" is a string. It is automatically converted to an integer value of -1000 and is added to 5. The result of this expression is -995. "-1000" || 5 The string concatenation operator (||) appends two strings together. The first value in the expression is a string "-1000". However, the second value is an integer constant 5. It is converted to a string constant of "5" and appended to "-1000" the result of this expression is "-10005". The default value for an unassigned variable is either an integer ZERO (0), a string NULL ("") or a logical FALSE. The default value used is determined by the type of operation being performed. For example, RepeatCount will have default value of ZERO for the expression (5 + RepeatCount). The automatic conversion makes it easier to work with different kinds of data. It isn't necessary to keep track of different variable types or to use conversion functions. Most of the time, different data types can be used interchangeably without special consideration. The automatic conversion is described in the following sections so that predictable results can easily be achieved. 6-5 Order of Evalution Each operator has a "priority" that defermines the order of computation. For example, multiplication is performed before additon. The priority scale ranges from 1 to 8, where oparations with a priority of 8 are performed first and operations with a priority of 1 are last. The proirities cause expressions to be evaluated in the standard order of algabraic rules. Operators with the parenthesis are evaluated first, following by the next lower priority. Operators with the same priority are evaluated from left to right. All expressions allow the usage of parenthesis to change the order of evaluation or to clarity the intended usage. Numeric Operations These operators provide the basic arithmetic functions. They operate on integer values. If a value is a stirng or logical, it is converted into an integer. Number of Operation Values Priority Symbol ------------------------------------------ Unary Minus 1 8 - Unary Plus 1 8 + Multiply 2 6 * Divide 2 6 / or % Modulo 2 6 MOD or // Addition 2 5 + Subtract 2 5 - Unary Operators As in algabra, + and - can be used to indicate positive or negative numbers. A unary operator can precede a single value. The value can be a constant, a variable or an expression within parentheses. Unary operators have the highest priority. Examples: -8 +56 -Count -( x + y ) Multiply, Divide, Modulo, Add, and Subtract Operators These operations perform the basic algebaric operations. The modulo operation operation returns the remainder of an integer divide. Both the symbol // or the word MOD can be used. Expression Result ------------------------ 4 + 7 - 2 9 5 + 3 * 2 11 -8 - 6 / 2 -11 +6 - 11 MOD 3 4 +6 -11 // 3 4 NOTE: Currently you can use either / or % for Division. Future releases will use / for Floating Point Division and % for Interger Division. Your current scripts will be fully compatable with future versions if you use the % operator. 6-6 String to Integer Conversion If the first characters within the string represents an integer, the automatic conversion will recognize the value. Otherwise, an integer value of ZERO will be used. Sting Result ------------------------ "104" 104 "14 Times" 14 "Five" 0 "-86" -86 " -5 " 0 "Jacks" 0 Logical to Integer Conversion Logicals are either TRUE or FALSE. TRUE convertes to 1. FALSE converts to 0. Logical Result ------------------------ TRUE 1 FALSE 0 ON 1 OFF 0 YES 1 NO 0 ( 5 = 6 ) 0 ( 5 <= 6 ) 1 Sting Concatenation Operations The string concatenation operators append two strings together. The concatenate including space operator (|||) appends the two strings with a space between them. Number of Operation Values Priority Symbol ------------------------------------------------------------ Concatenate 2 4 || Concatenate including Space 2 4 ||| Expression Result -------------------------------------- "1234" || "5678" "12345678" "1234" ||| "5678" "1234 5678" 6-7 Integer to String Conversion If the value for a string operation is an integer, it will be converted to a string. The string equivalent will not contain leading speces or zeros. If the integer is negative, it will contain leading minus sign ("-"). Expression Result ------------------------------------------------------ "Score:" || 250 "Score:250" "Ending Value:" ||| ( 15 - 25 ) "Ending Value:-10" Logical to String If a logical value is used in a string operation, it will be converted to eithe "TRUE" or "FALSE". Expression Result ------------------------------------------------------ "Value > 100:"||| ( Value > 100 ) "Value > 100: TRUE" TRUE ||| FALSE ||| YES ||| NO "TRUE FALSE TRUE FALSE" Relational Relational operators compare two values to each other. These operations work with both integer and string values. The result of a relational comparison is a logical value. Number of Operation Values Priority Symbol ---------------------------------------------------------- LessThan 2 3 < GreaterThan 2 3 > LessThan or Equal 2 3 <= =< GreaterThan or Equal 2 3 >= => NotEqual 2 3 < > > < ~ = Equal 2 3 = = = : = If both values are integers, they are compared in the usual way. However, if either of the values are not integers, then both values are converted to strings. The results of string comparisons are similar to the way a dictionary is ordered. However, upper and lower case letters are not the same. The order of the letters are based on the ASCII character set ( see ASCII appendix ). Expression Result ----------------------------------------------------- 7 + 2 < 6 FALSE 5 - 7 ==- ( 12 / 6 ) TRUE "Five" <> "FIVE" TRUE "-15" = 5 * -3 TRUE ( string comparison ) 6-8 Boolean Operations Boolean operations work with logical values. Often they are used with the results from relational comparisons. Number of Operation Values Priority Symbol ------------------------------------------ NOT 1 8 NOT ~ And 2 2 AND & Or 2 1 OR | Xor 2 1 XOR && The OR operation is used to determine if either of two conditions is TRUE. The AND operation determines if BOTH conditons are TRUE. The XOR is used to ascertain when one of the values is TRUE but not BOTH. The NOT operation is similar to the unary minus. The unary minus changes the sign of a value. The NOT operation changes a TRUE value to FALSE, and a FALSE value to TRUE. Expression IntermediateResult Result ------------------------------------------------------------------ 3 <> 4 or 5 = 6 TRUE or FALSE TRUE 5 = 3 + 2 and 7 < 2 TRUE and FALSE FALSE 3 <= 7 and -5 >= -8 TRUE and TRUE TRUE not (5 = 5 and 6 <> 7 ) NOT ( TRUE ) FALSE Integer to Logical Conversion When the value for a logical operation is an integer, it will be converted to FALSE if the value is ZERO. Othewise, it is converted to TRUE. Expression Result ------------------------ 0 or 1 TRUE 1 and 5 TRUE NOT 5 FALSE String to Logical Conversion If the value for a logical operation is a string, it is converted to a TRUE when the STRING is "TRUE","ON", or "YES". The identification is only on the leading characters of the string. If the leading characters do not match, it is converted to FALSE. Expression Result ------------------------------------------------------- "TRUE" or "FALSE" TRUE "TRUE" and "ON" TRUE "TRUE" and " ON" FALSE "TRUE" and "ONCE" TRUE ( "ON" is identified in "ONCE" ) 6-9 Functions A function is an operation, which returns a single value, that can be used within an expression. Some functions do not require parameters. These functions are called System Variables. This is because their usage resembles that of variables. MouseX is an example of a System Variable. It can be used in any expression just as though is was a variable. However, it is a read-only variable. This means you can not use the LET Command to change its value. It is always equal to the "current" value of the horizontal position of the mouse pointer. Other functions require information, on the form of parameters, on order to perform its operation. A function can have one or more parameters, contained with parenthesis, and separated by commas. LET X = MAX { OldX , Y / " , 100 } This assignment demonstrates the Max Function. The parameter list for the function is contained within parenthesis. Each parameter is an expression. This means it can contain constants, variables, operatiors, and even other functions. Multiple parameters are separated by commas. As with operators, the parameters for functions have expected data types. The parameter is automatically converted to the required type. The function returns a single result. This way, the function cn be placed in an expression just as a variable or constant. Conversion Functions Within expressions, values are automatically converted to the type of data neeeded for an operation. However, the data type of the result is detemined by last operation performed. <integer> = Integer { expression } "string" = String { expression } «logical» = Logical { expression } Example: LET Count = "123" || "456" The variable Count is assigned the string value of "123456". Count could be successfully used in arithmetic operations. However, each time it is used it is converted ino an integer. If Count is primarily used as an integer, it would be more efficient to convert the value when it is assigned. LET Count = Integer { "123" || "456" } The Integer Function converts the value within the parenthesis into an intege. Likewise, the String and Logical Funcions convert values into strings and logicals. 6-10 Integer Functions The following functions allow you to work with in integer values. ABSOLUTE <integer> = ABSOLUTE ( <value> ) The Absolute Function returns the absolute value of an integer. If the value is positive or ZERO, ABSOLUTE returns the same value. If the value is negative, it returns the positive value. Expression Result ------------------------ ABSOLUTE (156) 156 ABSOLUTE (-66) 66 ABSOLUTE (0) 0 LIMIT <integer> = LIMIT ( <limit1> , <limit2> , <test value> ) The Limit Function returns a value within a specified range. The first two values, <limit1> and <limit2> indicate the minimun and maximum values in the range. The thrid parameter is the value to test. If this value is between the two limits, the Limit Function returns the value unchanged. If it is less than the low limit, it returns the low limit value. If it is greater then the high limit, it returns the high limit value. Expression Result --------------------------------- LIMIT (0,100,89) 89 LIMIT (-300,-100,45) -100 LIMIT (900,400,0) 400 MAX <intege> = MAX ( <value> { , <value> , ...} ) The Max Funtion returns the value of the highest parameter. The Max Function can have one or more parameters. Expression Result --------------------------------- MAX (6,-1000,66,-5) 66 MAX (-10,-5) - 5 MAX (6-5,7*3,-1) 21 MIN <integer> = MIN ( <value> { , <value> , ...} ) The Min Function returns the value of the lowest parameter. The Min Function can have one or more parameters. Expression Result --------------------------------- MIN (100,5000,200) 100 MIN (-5*6,-1) - 30 MIN (5,7,-3,10,-5,88,8) - 5 6-11 RANDOM <integer> = RANDOM ( <minimum> , <maximum> ) The Random Function returns a random integer between and including the <minimum> and <maximum> values. Expression Result --------------------------------------------- RANDOM (5,20) any value between 5 and 20. SIGN <integer> = SIGN ( <value> ) The Sign Function returns the sign of the value. If the value is positive, it returns 1. If the value is ZERO (0), it returns 0, Otherwise, it returns -1. String Functions The string frunctions allow you to manupulate and work with strings. ASCII <integer> = ASCII ( "string" ) The ASCII Function returns the ASCII value of the first cahracter in the supplied string. The ASCII value is a positive integer between o and 255. Expression Result ------------------------ ASCII ( "A" ) 65 ASCII ( "m" ) 109 ASCII ( "more" ) 109 ASCII ( "<" ) 60 CHAR "string" = CHAR ( <integer> ) The Char Function returns a single character string cooresponding to an ASCII intege. The ASCII values range from 0 to 255. Expression Result ------------------------ CHAR (65) "A" CHAR (109) "m" CHAR (60) "<" 6-12 NUNBEROFCHARS <integer> = NUMBEROFCHARS ( "string" ) The NumberOfChars takes a string parameter, and returns the number of characters. Expression Result --------------------------------------------------- NumberOfChars ( "Hello!" ) 6 NumberOfChars ( "Spanish Inquisition" ) 20 NumberOfChars ( -67 ) 3 LOWERCASE "string" = LOWERCASE ( "string" ) The LowerCase Function converts uppercase characters within a string to lowercase. All other characters remain unchanged. Expression Result -------------------------------------------------- LOWERCASE ( "ABCdef123#$%" ) "abcdef123#$%" UPPERCASE "string" = UPPERCASE ( "string" ) The UpperCase Function converts lowercase characters within a string to uppercase. All other characters remain unchanged. DUPESTRING "string" = DUPESTRING ( "string" , <count> ) The DupeString duplicates a string a specified nymber of times. It returns a single string. Expression Result -------------------------------------------------- DUPESTRING ("*",10) "**********" DUPESTRING ("-",6) "------" DUPESTRING ("Hello! ",3) "Hello! Hello! Hello! " TRIMSTRING "string" = TRIMSTRING ( "string" ) The TrimString Function removes leading and trailing spaces and TAB characters within the remaining string are replaced with a single space. Expression Result ---------------------------------------------------- TRIMSTRING (" This is a Test") "This is a Test" TRIMSTRING ("Hello Out there! ") "Hello Out there!" 6-13 INSERTCHARS "string" = INSERTCHARS ( "source","destination",<offset> ) The InsertChars Function inserts a source string into the distination string at the specified offset. If the offset is greater than the length of the destination string, the source string is appended to the end of the destination. Expression Result ----------------------------------------------- INSERTCHARS ("...","123456",4) "1234...56" REMOVECHARS "string"=REMOVECHARS ( "source",<starting offset>,<length> ) The RemoveChars Function returns a string with specified characters removed. The first parameter is the source string from which to remove the characters. The second parameter specifies the starting offset of the characters to be removed. The last parameter indicates the number of characters to remove. Expression Result ------------------------------------------ REMOVECHARS ("12345",3,2) "125" REMOVECHARS ("Hello!",5,1) "Hell!" REMOVECHARS ("Hello!",5,-1) "Hello!" FINDCHARS <integer> = FINDCHARS ( "source","search",<starting offset> ) The FindChars Function searches the contents of a source string for a matching string. The <starting offset> indicates the offset within the "source" string to begin the search. The "search" string must match identically. If the string is found, FindChars returns the offset within the "source" string of the first character of the matching string. If the string is not found, FindChars returns a ZERO (0). Expression Result ------------------------------------------ FINDCHARS ("Hello Bill!","Bill",1) 7 FINDCHARS ("Hello Bill!","Fred",1) 0 FINDCHARS ("This is it!","is",1) 3 FINDCHARS ("This is it!","is",4) 5 6-14 GETCHARS "string" = GETCHARS ( "source",<starting offset>,<length> ) The GetChars Function returns a portion of a string. The <starting offset> indicates the starting character of the substring. The <length> indicates the number of characters to include. Expression Result ------------------------------------------ GETCHARS ("Brainpower",2,4) "rain" GETCHARS ("Hello!",4,10) "lo!" GETCHARS ("Jim Finney",20,1) "" FINDWORD <integer> = FINDWORD ("source","search word" {,<startwordnumber> {,"worddelimiters"}}) The FindWord searches a "source" string for a matching "search word" and returns its word number. If the word is not found, it will return a ZERO (0). The optional <StartWordNumber> allows you to specify a starting word number to begin the search. If it is not specified, it defaults to 1. The "WordDeflimiters" can contain characters indicating the characters that separate word. Expression Result ------------------------------------------------------------ FINDWORD ("This is a sample sentence.","sample") 4 GETWORD "string" = GETWORD ("source",<wordnumber> {,"worddelimiters"}) The GetWord Function returns a specified word nymber from the "source" string. The <wordnumber> indicates which word to return. A <wordnumber> of 1 returns the first word. A 2 returns the second word. By default, words are separated by spaecs. You can supply a list of characters in the optional parameter "worddelimiters". Expression Result ----------------------------------------------------- GETWORD ("The dog Smiled.",3) "Smiled" GETWORD ("DF1:Sounds/Bird.snd",2,":/") "Sounds" 6-15 POSITIONOFWORD "string" = POSITONOFWORD ("source",<wordnumber> {,"worddelimiters"}) The PositionOfWord Function returns the offset into the "source" string for a specified word <wordnumber>. If the <wordnumber> is greater than the number of words in the "source" string, PositionOfWord returns a ZERO (0). The "worddelimiters" work in the same way as in GetWord allowing you to specify the charcaters separating words. Expression Result --------------------------------------------------- POSITONOFWORD ("Word1 Word2 Word3",2) 7 BUMPREVISION "string" = BUMPREVISION ( "name" ) The BumpRevision Function changes the revision of a "name" in the same manner the Workbench Duplicate function does with a filename. Expression Result ------------------------------------------ BUMPREVISION ("Record") "Copy of Record" BUMPREVISION ("Copy of Record") "Copy 2 of Record" BUMPREVISION ("Copy 2 of Record") "Copy 3 of Record" EVALUATEEXPRESSION results = EVALUATEEXPRESSION ( "string" ) The EvaluateExpression Function evaluates the string parameter. The string must contain a valid expression. EvaluateExpression returns the result of the evaluation. If there is any uncertainty as to the validity of the expression, a run time error can be avoided by using the VerifyExpression Function. This function allows expressions to be created at run time. This can be quite powerful. However, it is error prone and it can make the script difficult to read. Expression Result ------------------------------------------ EVALUATEEXPRESSION ("5+6") 11 EVALUATEEXPRESSION ("123" || "-23") 100 6-16 VERIFYEXPRESSION «logical» = VERIFYEXPRESSION ( "string" ) The VerifyExpression Functon evaluates the string parameter. However, it does not return the resulting value of the evaluation. It returns a TRUE if the expression is successfully evaluated. Otherwise, it returns a FALSE. This function also allows an expression to be verified before using the EvaluteExpression. Expression Result --------------------------------- VERIFYEXPRESSION ("5+6") TRUE VERIFYEXPRESSION ("6+*7) FALSE VERIFYEXPRESSION ("(5+6") FALSE